Skip to content

schema-family-reference.md

Latest commit

 

History

History
168 lines (130 loc) · 9.74 KB

schema-family-reference.md

File metadata and controls

168 lines (130 loc) · 9.74 KB

Schema Family Reference

This document tells you which schema family to use before you start reading individual fields.

Use this file when you need the right abstraction level quickly. Use schema-reference.md after you already know which family you need.

Family 1: capsule artifact shape

Use this family when you need to read, validate, or generate a capsule artifact itself.

Choose this family when you are building:

  • a capsule parser
  • a capsule writer
  • a validator input generator
  • source-level tooling that needs the public artifact shape
  • code-generation or polyglot tooling that prefers one-file schema imports via schema-bundles.md

Family 2: validator transport and HTTP envelopes

Use this family when you need public validator request and response shapes rather than raw capsule structure alone.

Choose this family when you are building:

  • a validator client
  • API tests
  • a request/response parser
  • transport-level integration code
  • code-generation or polyglot tooling that wants one-file envelope imports via schema-bundles.md

Family 3: portability and archive contracts

Use this family when you need the bounded public export/import posture instead of validator transport.

Choose this family when you are building:

  • archive exporters
  • replay tooling
  • trust review around portability claims

Family 4: machine-readable repo governance summaries

Use this family when you are not consuming capsule data directly, but instead need machine-readable summaries of the public repo surface itself.

Core repo summary schemas:

Reviewer and release posture schemas:

Boundary, trust, and maturity schemas:

Workflow, audience, and adoption schemas:

Choose this family when you are building:

  • external review automation
  • release audits
  • contract catalogs
  • maintainer-facing dashboards for the public repo

Family 5: client recipe navigation contract

Use this family when you need a bounded machine-readable map of the published consumer snippets rather than the capsule, validator, or archive payload contracts themselves.

Choose this family when you are building:

  • tooling that chooses the right public recipe automatically
  • IDE or UI affordances that surface recommended starts per runtime lane
  • docs automation that needs a bounded contract for snippet discovery
  • package or repo consumers that want to validate recipe discovery before execution

Which family is strongest for what

  • Use capsule-schema.json when the question is about capsule outer shape.
  • Use capsule-schema.bundle.json when you need the same outer shape as a single-file schema artifact.
  • Use neuro-concentrate.schema.json when the question is about the semantic-summary subobject.
  • Use validator-api-envelopes.schema.json when the question is about public validator request or response object shape.
  • Use validator-api-envelopes.bundle.json when you need the same public validator request or response object shape as a single-file schema artifact.
  • Use validate.openapi.json when the question is about routes, methods, or HTTP-level transport semantics.
  • Use archive-bundle.schema.json when the question is about portability/export bundle shape.
  • Use client-recipe-index.schema.json when the question is about the bounded shape of the published client-recipe navigator.
  • Use the public-*.schema.json family when the question is about this repository's own machine-readable review, release, provenance, or governance summaries.

What not to do

  • Do not start from prose if you already know you need a machine-readable contract.
  • Do not treat the TypeScript or Zod projections as stronger than the JSON Schema files.
  • Do not use repo-governance schemas when what you really need is capsule or validator transport shape.
  • Do not use the client-recipe navigator schema as proof of validator runtime behavior; it only describes snippet discovery and task routing.
  • Do not use the public schemas as proof of private runtime behavior that is intentionally out of scope here.