Preprint
Structured output as an interface contract
J. Ferreira, M. Costa
·
·
14 pages
Treating model output schemas as versioned API contracts rather than prompt artefacts. We describe the migration path used on two client systems, in which every schema change ships as a version with a compatibility test against downstream consumers. On both systems the practice prevented a class of silent failure that had previously reached production, and made model swaps a routine operation rather than a project.
When a model's output feeds another system, the shape of that output is an interface. Most teams treat it as part of the prompt, which means it changes silently and breaks things downstream. This preprint describes what happened when we treated it as a versioned contract instead.
Key findings:
Schema versioning caught four breaking changes before deployment across the two systems in six months
The failure it prevents is silent: outputs that parse but mean something different than the consumer assumes
Model swaps became routine: both systems changed underlying models without downstream changes
Method: both systems ship every schema change as an explicit version, with contract tests run against recorded consumer expectations. Prompts may change freely; the contract may not, except by version.
The cost is small and front-loaded. The benefit compounds every time the model, the prompt, or the provider changes underneath a stable contract.
CITATION
Ferreira, J., & Costa, M. (2025). Structured output as an interface contract. Preprint.
CONFRONTO