Start with the consumer contract
Define the smallest object your next system actually needs. The official guide supports schema-constrained output for supported JSON Schema features and also documents looser JSON modes. Prefer a precise schema when downstream code depends on fields.
Use descriptions for meaning and constraints for shape. Keep schema size under control: deeply nested, weakly described objects make both evaluation and migration harder.
Validate shape and meaning
Schema conformance can guarantee that required keys and types match supported constraints. It cannot prove that a date exists, a citation supports a claim, or a business decision is permitted.
Parse into a runtime validator, then apply domain rules. Reject or repair invalid semantics through a bounded path; never silently coerce a high-impact value.
- Schema check: types, required keys, allowed values.
- Domain check: ranges, referential integrity, authorization.
- Evidence check: cited source actually supports the field.
Version the boundary
Include a schema version when output is stored or passed across services. Additive changes can be compatible; renamed fields and changed meaning require migration.
Build fixtures for valid, boundary, and intentionally impossible cases. When changing model configuration, compare both conformance rate and semantic accuracy.