A schema read by two audiences
A Socratic walk-through of a schema read by two audiences — reasoned out one step at a time, not lectured.
The question we started with
THE QUESTION #How can one declaration serve as a machine's validator and a reader's instructions at the same time?
A tool exposed to an AI assistant carries a single JSON Schema describing its inputs. That schema is used to reject malformed calls — a strict, mechanical job with a yes-or-no answer. It is also the only thing the model reads to work out what the tool is for and how to fill it in — a loose, interpretive job with no right answer at all.
Those sound like documents that ought to be written differently, by different people, for different purposes. Yet it is one artefact. How does a single declaration manage to be both, and what happens when the two readings pull apart?
Reasoning it through
REASONING #Start by noticing something about JSON Schema that is easy to walk past. Its keywords are not all the same kind of thing. Some of them assert: type, required, enum, minimum, pattern. Each one can make a document invalid. Others merely annotate: title, description, examples, default, deprecated. The specification is explicit that these never affect validity — a validator collects them and passes them along, but no annotation can ever cause a rejection.
Sit with what that separation makes possible. Because annotations are inert to the machine, prose can be added to a schema without any risk of changing what the schema accepts. There is no tension to resolve, because the two readers are looking at disjoint sets of keywords. The document is not doing two jobs with the same words; it is carrying two vocabularies in one envelope.
But that is only half the story, and the more interesting half is the overlap. Consider enum. To a validator it is an assertion: reject anything not in this list. To a model it is the single most informative thing in the schema — it says not just what is allowed but what the concept is, because the values are the concept's own vocabulary. A field described only as a string tells a model almost nothing; the same field with an enum of three values tells it what kind of thing the argument is. So enum genuinely serves both audiences at once, and it serves them with the same content rather than with parallel content that could drift apart.
Do you see why that is the valuable case? Anything that is only prose can go stale — a description saying a field takes a date while the pattern says otherwise. Anything expressed as an assertion cannot drift, because it is the thing being enforced. So the design instinct that falls out is: push as much meaning as you can into assertion keywords, where it is checked, and use annotations for what genuinely cannot be checked — purpose, consequence, when to prefer this tool over another.
Now the honest complication. The model does not read the schema the way a validator does; it reads it as text, in a context window, alongside everything else. That has two consequences the validator never faces. First, length costs something real: every tool description occupies tokens that a long list of tools multiplies. Second, a strict regular expression that satisfies a validator perfectly may communicate nothing — a model handed a dense pattern is often better served by a description saying what the format is, and an examples entry showing one.
There is also a difference in what "wrong" means. For the validator, a schema is correct if it accepts exactly the valid inputs. For the model, a schema is correct if it leads to the right call being made — which includes the tool not being called when it should not be. That second property cannot be tested by any validator, only observed in use, and it is why descriptions in practice end up carrying negative guidance: what this tool does not do, and what to use instead.
The analogy
THE ANALOGY #Think of a recipe card that also works as a shopping list. The quantities and ingredient names serve both readings and cannot disagree with themselves — two eggs is two eggs at the shop and at the stove. Around them sit the method notes: fold gently, rest for an hour. Those matter enormously to the cook and mean nothing at the till, and precisely because the till ignores them, they can be as discursive as they need to be without ever making the shopping wrong.
a shopper and a cook are usually the same person with the same understanding, whereas a validator is literal and a language model is inferential — the model may act on a wording the validator would never notice, so an ambiguous description is a real defect even though nothing rejects it.
Clarifying the model
THE MODEL #Three refinements.
The first corrects a common assumption: that the annotations are documentation and therefore optional. In this setting they are not documentation about the interface, they are the interface for one of its two consumers. A tool with a rigorous schema and an empty description is, from the model's point of view, an unlabelled button. Reviewing a schema means reading the prose as seriously as the types.
The second is about where to put a constraint when you have a choice. If a value must be one of four things, an enum beats a sentence saying so — it is enforced, it is compact, and it informs. If a value must be a date in a particular format, both help: the pattern makes it enforceable and the description makes it understandable. If a constraint is relational — this field is required only when that one is set — schema languages can express some of it awkwardly, and a plain sentence is often the more honest carrier, with the real check done inside the tool.
The third is a caution about self-description in general. A schema is a claim, and nothing in the mechanism verifies that the claim matches the implementation. A tool whose description promises a read-only lookup and whose code writes is not caught by any validator on either side of the wire. The schema tells you what the author said; only the running system tells you what is true.
A picture of it
THE PICTURE #How to readthe central class is the single declaration; the two classes pointing at it are its two audiences, and their listed members show what each one actually consumes. Note that the validator's list stops at the assertion keywords — annotations are invisible to it by specification. The composed class at the bottom is the overlap worth designing for: the one keyword both audiences read, which is why meaning placed there cannot go stale.
What became clearer
WHAT CLEARED #The trick is not that one document is cleverly ambiguous, but that JSON Schema keeps assertions and annotations in separate keyword families — so prose can be added freely without changing what is accepted. The craft lies in the overlap: constraints such as enum that constrain and explain with the same words are the parts that can never drift, and the more of a tool's meaning that lives there rather than in prose, the less there is to keep in sync.
Where to go next
ONWARD #- How to budget schema prose when a client exposes dozens of tools and every description competes for the same context window.
- Whether evaluating a schema by whether the right call gets made can be automated, or whether it remains an observational judgement.
- What it would take to verify that a tool's declared behaviour matches what its implementation actually does.
Key terms
TERMS #| Term | What it means |
|---|---|
| JSON Schema | a vocabulary for describing the shape of JSON data, used both to validate documents and to describe interfaces. |
| Assertion keyword | a schema keyword such as type, enum or required that can make a document invalid. |
| Annotation keyword | a schema keyword such as title, description or examples that carries information but never affects validity. |
| inputSchema | the schema a tool publishes describing the arguments it accepts. |
| Self-describing interface | an interface that ships its own machine-readable description, so a caller can learn to use it without out-of-band documentation. |
Every term the collection defines is gathered in the glossary.