JSON Schema Design
Designing robust JSON schemas is the foundation of any reliable Meridian integration. This recipe walks through how to shape structured outputs so your LLM responses are parseable, predictable, and forward-compatible. We cover the three principles that separate brittle schemas from ones that survive model upgrades and edge cases.
1.Prefer flat shapes over deep nesting
Models reliably emit shallow objects. Every level of nesting compounds the probability of a malformed brace or missing field. When you can, flatten related fields into a single object with descriptive prefixes rather than nesting two or three layers deep. Reserve nesting for truly hierarchical data like trees or comment threads.
2.Make every field required, use nulls for optionality
Optional fields confuse models. Half the time the field appears, half the time it doesn't, and your parser has to handle both. Instead, mark every field as required and allow null as a valid value. The model now has one clear contract: emit every key, every time.
3.Use enums for closed sets and describe them
When a field has a known set of valid values, lock it down with an enum and add a description explaining each option. This raises adherence dramatically and gives downstream code permission to switch on the value without defensive fallbacks.
Example schema
{
"type": "object",
"required": ["summary", "sentiment", "tags", "confidence"],
"properties": {
"summary": { "type": "string" },
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"],
"description": "Overall tone of the input"
},
"tags": { "type": "array", "items": { "type": "string" } },
"confidence": { "type": ["number", "null"] }
},
"additionalProperties": false
}