Why Schema Descriptions Fail
Telling the model "return JSON with these fields" works sometimes. Adding a JSON Schema definition helps. But both approaches still produce inconsistent results: wrong types, missing required fields, extra fields you did not ask for.
The problem is that schema descriptions are abstract. The model has to infer what the output looks like from a description of rules.
Examples are concrete. Show the model two good outputs and one bad output with an explanation, and it will replicate the pattern reliably.
The Pattern
1 Extract the key information from the following text. 2 3 ## Output Format 4 Return JSON. Follow the examples exactly. 5 6 ### Example 1 7 Input: "Sarah joined the team on March 3rd as a backend engineer." 8 Output: 9 { 10 "name": "Sarah", 11 "role": "backend engineer", 12 "start_date": "March 3rd", 13 "department": null 14 } 15 16 ### Example 2 17 Input: "Marcus from the design team transferred to product management last Tuesday." 18 Output: 19 { 20 "name": "Marcus", 21 "role": "product management", 22 "start_date": "last Tuesday", 23 "department": "design" 24 } 25 26 ## Task 27 Input: {{USER_INPUT}} 28 Output:
Why This Works
The model sees exactly what output shape you want. Null handling is shown (not inferred). Date formatting is shown. Field naming is shown. There is nothing to infer.
The empty `Output:` line at the end signals that the next token should be the JSON. This prevents preamble like "Here is the extracted information:".
How Many Examples
- 2 examples: covers happy path and one edge case (null fields, different date format)
- 3 examples: adds a second edge case
- 4+ examples: diminishing returns, costs more tokens
Start with 2. Add a third only if you see a specific failure pattern in production.
Common Failure Modes
Extra fields: the model adds a field not in your schema. Fix: add a line to the system prompt: "Only return the fields shown in the examples. No additional fields."
String instead of null: the model returns `"none"` instead of `null`. Fix: show a null example explicitly, which the examples above do.
Wrapped output: the model wraps JSON in a markdown code block. Fix: add `Return raw JSON only. No markdown.` to the prompt.
Comments (0)