Schema conventions

How machine-readable contracts will work once objects graduate from conceptual documentation. No domain schemas exist yet — this page defines the rules they will follow so the first ones aren't invented ad hoc.

The three layers of authority

1. Concept documentation (these docs) — semantics, rationale, invariants, examples. What the system means.
2. Machine-readable contracts — exact field-level constraints. What can appear on the wire and at rest.
3. Application code — implements the contracts. Code conforms to the docs and schemas; it never silently redefines them.

When the layers disagree, that is a bug in the lower layer or a reviewed change to the upper one — never an implicit override.

Formats

• JSON Schema — canonical contracts for persisted/domain objects, in schemas/*.schema.json at the repository root.
• OpenAPI — description of HTTP APIs, in openapi/tfp.openapi.yaml.
• MCP tool and resource contracts reuse the same underlying domain schemas. No incompatible parallel model of the same object.

Rules

• Conceptual meaning lives in the documentation; exact machine constraints live in checked-in schema files. Concept pages link to schemas, and do not duplicate full field lists.
• The schema reference pages in these docs will be generated or rendered from the canonical schema files (e.g. Mintlify's OpenAPI/schema generation), never manually retyped. A rename or type change must not require remembering to update multiple independent representations; once schemas exist, CI will treat drift as a failing check.
• Implementation TypeScript types are generated from, derived from, or automatically checked against the canonical schemas — not hand-maintained in parallel.
• Schemas are versioned; published versions are immutable.
• Any schema change with compatibility implications is intentional and reviewed, never a side effect of an implementation change.
• Field documentation records, for every field: type, required?, mutable?, default, semantics, validation, an example — and where it prevents mistakes, what the field explicitly does not mean.

The pipeline (in place since Stage 1A)

schemas/*.schema.json (JSON Schema 2020-12) is the domain truth. Each field carries a real description, examples, and an x-mutable annotation, so the explanation travels into generated docs, tooling, validation errors, and agent context. scripts/generate-schema-docs.mjs (pnpm docs:schemas) deterministically generates the full reference pages under reference/schemas/ and injects the compact field tables into concept chapters between BEGIN/END GENERATED markers — those tables are never edited by hand. OpenAPI and MCP tool schemas will reference or be built from these same files; Mintlify renders reference from the specs rather than from a second handwritten copy.

The first three schemas are the registry objects: Campaign, Problem, ProblemRevision. Later stages add their objects the same way.