Ask for a shape, not prose
When you need data back from AI in a fixed form, the reliable move is to hand it a schema, the defined shape of the thing you want, and have it fill that in, rather than describing the JSON you want in a prompt and hoping. The schema is a contract for what comes back.
Say it another way
A schema is a fixed shape you ask the AI to fill in, like a form with set fields, instead of letting it answer in free-flowing text. Hand it the form and the answer comes back in the exact shape you need, with nothing missing and nothing made up.
Doing this with Claude Code: Ask for a shape, not prose
Hand Claude a schema, the fields and their types, and ask it to fill that in, instead of describing the JSON you want in words. The shape then comes back guaranteed, and nothing extra rides along with it.
A schema earns its keep in five ways: a guaranteed shape, a shape that is not the same as the truth, a real empty instead of a guess, a forced shape you can route with and a clean value not just a clean shape.
A guaranteed shape, not a request. Ask for JSON by example and other output creeps in, a recommendation, a summary of the work, an extra field. With a recipe-card schema of a title, an ingredients list and a steps list, you get those fields and nothing else.
The shape is guaranteed, not the truth. The schema makes sure you get a well-formed card, but it cannot know that serves 4 is wrong for a recipe that clearly feeds six. Right shape, possibly wrong values, so you still check the meaning.
A real empty beats a guess. If a recipe never states a cook time, make that field nullable, so Claude returns nothing there rather than inventing thirty minutes just to fill the slot.
Force the shape and route with it. tool_choice decides whether a tool must be used at all and, when you offer several schemas, which one, so "any" turns Claude into a router that has to sort the input into the right shape instead of waffling. Force the extraction tool first too, so the facts are locked before any enrichment step reads them.
Pin the value, not just the shape. The schema guarantees the field exists, not that its value is clean, so add normalisation rules beside it (always Celsius, always grams) and give the awkward cases a home, an "other" plus detail for a known off-list value and an "unclear" for one the source does not settle.
Common questions
- Why is a schema better than asking for JSON by example?
An example only suggests the shape, so other output creeps in: a recommendation, a summary of the work, an extra field or a bit of commentary wrapped around it. A schema has to return exactly the fields defined and nothing else. - What does the schema actually guarantee?
Valid JSON with the right fields and types, every time, rather than something you have to parse and hope is well formed. The shape is guaranteed rather than requested. - Does a schema guarantee the values are right?
No. A serves count of four is a valid, allowed, non-empty number and nothing in the schema knows the recipe really feeds six. That truth lives in the source rather than in any rule, so checking it is still on you. - So where is the line between shape and meaning?
It is not shape versus meaning, it is what can be written as a rule versus what cannot. A field can be limited to a set of allowed values, allowed to be empty, or kept within a range, and the schema will hold all of that. - How do I stop it inventing a value?
Make the field nullable. A required field pushes the model to put something in it, and that something can be invented. Nullable gives it permission to say the value is not there, which is the honest answer when the source does not have it. - What about a value that does not fit any of my options?
Give the exception a home. An "other" option with a detail field handles a value you know but did not list, and an "unclear" option handles one you cannot tell from the source, so neither gets forced into the wrong bucket. - Can I use several schemas at once?
Yes, as a router. Define one for each kind of input, then force the model to call some tool, so it has to classify what arrived and route it to the matching one rather than waffling back in prose. - How do I make extraction run before anything else?
Force the extraction tool for the first step, then release the rest. The enrichment reads the extracted data, so the extraction has to be locked first or the enrichment is building on nothing. - The shape is right but the values are inconsistent. What is missing?
A normalisation rule alongside the schema. A temperature might arrive as celsius, fahrenheit or a gas mark, so the rule says which form to settle on, because the schema on its own cannot say convert one to the other.
Back to For developers. The craft around it is Working with AI.