PubFi DSL Server Contract

Overview

This skill defines the server-side contract for executing PubFi DSL requests. The server only accepts structured DSL and maps requests to a fixed, audited OpenSearch query shape. The server does not accept SQL, OpenSearch DSL, or natural language compilation.

When To Use

• You are implementing the DSL validation layer.
• You are defining or auditing the allowed query templates.
• You are designing the response envelope and error model.

Core Rules

• Reject any request that includes SQL, OpenSearch DSL, or unknown fields.
• Validate against the schema before execution.
• Enforce hard limits for time window, top-k, fields, and aggregation sizes.
• Only execute allowed aggregation primitives (terms, date_histogram, cooccurrence).
• Do not compute business metrics server-side. Return documents and aggregation results only.

Required Server Behaviors

• Provide a schema endpoint that lists allowed fields, aggregation kinds, and hard limits.
• Provide a query endpoint that accepts DSL and returns a deterministic response envelope.
• Log request metadata for audit and billing reconciliation.

Error Model

The server returns errors using ApiEnvelope codes and English messages.

• ERR_INVALID_PAYLOAD: The request violates schema or limits.
• ERR_INTERNAL: The service failed unexpectedly.

Rate limiting and quota enforcement are out of scope for this contract draft and should be implemented at the gateway layer.

References

• See references/contract.md for endpoint definitions, response envelopes, and template mappings.