pubfi-dsl-server-contract
Scannednpx machina-cli add skill helixbox/pubfi-skills/pubfi-dsl-server-contract --openclawPubFi 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
schemaendpoint that lists allowed fields, aggregation kinds, and hard limits. - Provide a
queryendpoint 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.mdfor endpoint definitions, response envelopes, and template mappings.
Source
git clone https://github.com/helixbox/pubfi-skills/blob/main/skills/pubfi-dsl-server-contract/SKILL.mdView on GitHub Overview
Defines the server-side contract for executing PubFi DSL requests. The server accepts only structured DSL and maps requests to a fixed, audited OpenSearch query shape, rejecting SQL, OpenSearch DSL, or unknown fields. This contract governs schema validation, hard limits, and the deterministic response envelopes.
How This Skill Works
The server validates payloads against a predefined schema before execution, rejecting anything with SQL, OpenSearch DSL, or unknown fields. It exposes a schema endpoint listing allowed fields, aggregation kinds, and hard limits, and a query endpoint that accepts DSL and returns a deterministic response envelope. Only permitted aggregations (terms, date_histogram, cooccurrence) are executed, while request metadata is logged for audit and billing reconciliation.
When to Use It
- 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.
- You need to enforce hard limits for time windows, top-k, fields, and aggregation sizes.
- You are integrating server behavior with gateway logging and audit trails.
Quick Start
- Step 1: Create a schema endpoint that lists allowed fields, aggregation kinds, and hard limits.
- Step 2: Implement a query endpoint that accepts DSL and returns a deterministic response envelope.
- Step 3: Add request metadata logging and enforce core rules (reject SQL/OpenSearch DSL, apply hard limits).
Best Practices
- Enforce strict schema validation before execution to reject invalid payloads early.
- Provide a schema endpoint that lists allowed fields, aggregation kinds, and hard limits.
- Only allow approved aggregation primitives: terms, date_histogram, cooccurrence.
- Do not compute business metrics server-side; return documents and aggregation results only.
- Log request metadata for audit and billing reconciliation; surface clear English error messages via ApiEnvelope codes.
Example Use Cases
- Implement a schema endpoint that exposes allowed fields, aggregation kinds, and hard limits.
- Validate a DSL payload against the schema before passing it to the query engine.
- Return a deterministic response envelope for a given DSL input.
- Reject payloads containing SQL or OpenSearch DSL, returning ERR_INVALID_PAYLOAD.
- Handle errors using ApiEnvelope codes (e.g., ERR_INVALID_PAYLOAD, ERR_INTERNAL) with clear English messages.
