Skip to content

api-envelopes.md

Latest commit

 

History

History
131 lines (102 loc) · 10.4 KB

api-envelopes.md

File metadata and controls

131 lines (102 loc) · 10.4 KB

API Envelopes

This repository publishes the validator OpenAPI document and a small set of concrete API payload examples for integrators.

The request and response examples are also covered by ../schemas/validator-api-envelopes.schema.json, which gives tooling a machine-readable contract bundle for the public envelope layer.

For intentionally schema-invalid validator-envelope fixtures that should fail before any live route semantics matter, also inspect:

If you need source-level consumer artifacts instead of raw JSON Schema alone, also inspect:

If you need installed-package consumer artifacts for the bounded shared error-envelope family instead of repo-relative imports, also inspect:

If you need compact machine-readable route data instead of full OpenAPI or prose docs, also inspect:

The compact route layer now carries response-status-to-envelope mappings and bounded auth/query metadata, so SDK and client builders can recover practical route behavior without scraping the full OpenAPI document first.

Compact family map

The compact envelope-family surface publishes:

  • request families: validateSingleRequest, validateBatchRequest, validateFixRequest
  • response families: validatePassResponse, validateFailResponse, validateBatchResponse, validateFixResponse, gatesResponse, statsResponse, simpleErrorResponse
  • shared definitions: validationOptions, validatorIssue, warningItem, gateDescriptor

Use ../references/validator-envelope-families.json when you want those families as a compact route-linked machine-readable surface instead of walking schema defs or prose sections manually. Use ../references/validator-routes.json when you need the per-route auth, query, and response-status map that sits beside those families.

If you need a cross-language raw-JSON consumer path outside the Node runtime, also inspect:

Covered example files

Envelope rules

  • POST /api/validate Uses { capsule, options, autoFix }.
  • POST /api/validate/batch Uses { capsules, options }.
  • POST /api/validate/fix The current public example surface uses { capsule, options }. Policy variants may exist upstream, but the public repository only schema-covers the documented example envelope.

The public repo currently includes concrete examples for all published request and support-route success envelopes documented here, plus a dedicated bounded GET /api/validate/stats failure sample and copyable live client recipes for validate, batch, fix, gates, and stats. That keeps the reference surface useful without trying to mirror every internal runtime path.

The fix response sample is intentionally illustrative: it is derived from the published OpenAPI contract and from local validator behavior on the public negative G16 example, not from a deployed public HTTP trace.

The fixtures under ../examples/api-invalid/ are different: they are intentionally not valid public request/response envelopes. They exist to teach raw-schema consumers what should be rejected directly by the envelope schema bundle.

For the higher-level fail-closed summary across validator, OpenAPI, and portability surfaces, see failure-model.md.

Why this matters

OpenAPI alone tells tooling what shapes exist. Example envelopes show human readers and downstream builders how those shapes feel in real use, especially when validator options or mixed batch outcomes are involved.

The dedicated API envelope schema keeps these example files machine-readable without forcing consumers to infer shape rules from prose alone.

The published validator API projections strengthen that path further by giving TypeScript and Zod consumers a public-safe source-level envelope layer for validate request families, sample-driven TypeScript and Zod request readers, a repo-relative and installed-package TypeScript fetch bridge for the published validator route family, and shared validator-route constants while staying subordinate to the stronger JSON Schema and OpenAPI surfaces.