A county IT group defines a structured-output schema for asset-retirement records that three separate applications will consume. Today the meaning of ambiguous fields such as disposition_date is explained in a paragraph inside the prompt, and one team has already copied the schema into a new service without that paragraph. What practice should the group adopt?

A schema consumed by three applications is a distributed artifact, and whatever a consuming team needs in order to use it correctly has to be part of what they import. Semantics for a field such as disposition_date explained in a paragraph inside the prompt are not part of that artifact, which is why one team has already carried the schema away without them.

Writing a description for each field inside the schema puts meaning into the thing that gets versioned, imported, and reviewed. It serves two audiences at once, the model, which reads descriptions as in-context guidance about what belongs in disposition_date, and the engineers building consumers, who no longer have to locate a prompt to learn what a field means. One definition exists instead of several drifting copies.

A wiki page linked from READMEs still sits outside the contract and degrades the moment someone imports the schema without following the link; renaming the field to date_1 strips away the little meaning the name carried and pushes semantics further from the contract; and having the model explain every field in every response spends tokens restating documentation while producing per-call prose no consumer can treat as a stable definition.

Exam caveat: descriptions are guidance to the model, not validation, so a field described as an ISO date still needs a format constraint if the value must parse. Operational check: import the schema into a fresh service with no access to the original prompt and confirm a developer can populate disposition_date correctly from the schema alone.