Skip to content

Output Schema

Declarative artifact — instantiates Domain–Codomain Delimitation

Declares the fields, formats, and value categories a function or service is allowed to emit, so nothing outside its codomain can be returned in a well-formed response.

An Output Schema is a static, declarative contract that pins down the shape of everything a unit is permitted to return: which fields appear, what type each holds, which enumerated categories are legal, and what is forbidden. Its defining move is that it bounds the output side structurally and up front — before any value is computed — rather than judging a produced value at runtime (that is Output Validation) or declaring input-and-return types in code (that is Type Signature). The schema is the single source both the producer and every consumer compile against, so the codomain stops being folklore and becomes a machine-checkable object.

Example

A geocoding service returns coordinates for an address. Its Output Schema declares a response object with exactly lat and lng (numbers), a confidence field (a number in [0,1]), and a match_type that must be one of rooftop, interpolated, or approximate — with additionalProperties: false, so no other key is legal. One day a new provider integration starts returning match_type: "best_guess" alongside a free-text note field explaining its reasoning. Neither is in the codomain. Because the schema is closed, the response fails validation at the boundary instead of quietly flowing downstream, where a billing system that trusted match_type to be one of three values would have mis-routed the record. The schema didn't judge whether the coordinates were good — only that the response could not carry a shape the codomain never promised.

How it works

The schema enumerates every legal field with its type, marks each required or optional, constrains value sets with enums and formats (patterns, ranges, cardinality), and — critically — decides whether unspecified fields are allowed at all. Closing the schema (additionalProperties: false) is what turns "here are the fields we use" into "these are the only fields that may appear," which is the difference between describing the codomain and bounding it. Because it is declarative, it can be published, diffed, and versioned as an artifact in its own right.

Tuning parameters

  • Open vs. closed — whether undeclared fields are tolerated. Closed pins the codomain tightly but breaks on benign producer additions; open is forgiving but lets the output surface drift.
  • Enum granularity — how finely output categories are pinned. Coarse enums admit ambiguous responses; fine ones are precise but brittle when a new legitimate category appears.
  • Required vs. optional — how much of the codomain is guaranteed present versus merely permitted. More required fields give consumers stronger promises but reject more partial results.
  • Format strictness — regexes, ranges, and length limits. Tight formats catch malformed values early but reject harmless variants.
  • Versioning strategy — inline version tag vs. content negotiation, governing how consumers migrate when the schema changes.

When it helps, and when it misleads

Its strength is that it makes the output contract explicit, shared, and enforceable by machines rather than memos — a consumer can build against a guaranteed shape, and an undeclared field fails fast at the edge. Its central limit is that a schema bounds structure, not meaning: a latitude of 999.0 is a perfectly valid number and sails through, so schema-conformance is necessary but never sufficient. The classic misuse is loosening the schema — flipping it open, making everything optional — to make a producer's non-conforming output "pass," which quietly widens the codomain to fit reality instead of fixing the producer.[1] The discipline is to keep the schema closed and hand semantic checks (is this value plausible, is it in range) to Output Validation, which runs on the value, not the shape.

How it implements the components

  • output_codomain — the enumerated set of permitted fields, types, and categories is the declared codomain, written as an inspectable artifact.
  • output_conformance_rule — additionalProperties: false, required-field lists, and enum constraints are the rules that stop an output from exceeding its allowed form.

It says nothing about the input side (input_domain, membership_criteria — see Type Signature and Eligibility Criteria), does not check produced values at runtime (that is Output Validation), and does not steward the boundary as it changes (Scope Change Review).

  • Instantiates: Domain–Codomain Delimitation — the Output Schema is the artifact that makes the codomain concrete and checkable.
  • Sibling mechanisms: Output Validation · Type Signature · Contract Test Suite · Service Scope Statement · Model Applicability Card · Input Validation Gate · Eligibility Criteria · Clinical Indication Criteria · Scope Change Review · Unsupported Case Triage Workflow

References

[1] JSON Schema is a real, widely-used standard for declaring the permitted structure of JSON documents (types, enums, required fields, additionalProperties). It is the canonical way an Output Schema is made machine-checkable, and its additionalProperties: false keyword is exactly the "closed codomain" control described above. ↩