Nested JSON Output — Arrays and Objects
Flat schemas are easy; reliability gets hard at the first nested array. How to contract arrays and objects so the structure survives the model.
Overview
Most JSON contract failures hide in the nesting: the array that comes back as a comma-joined string, the object that flattens into prefixed keys, the list of objects where item shapes drift between elements. Contracting nested output means showing it: the example response must demonstrate the exact nesting, and field descriptions must define what array items and object properties contain. This resource loads a user-profile schema with both an array field and an object field — the smallest schema that exercises every nesting rule.
Workflow
-
Generate and study the example
The example demonstrates the array AND the object nesting explicitly — the model imitates what it sees.
-
Define items in descriptions
'Topic interests, lowercase tags' defines array items; 'with street and city' defines object properties. Descriptions are the nested schema.
-
Watch the null rule on nested fields
An unknown address is null — not an empty object, not omitted. One convention, applied at every depth.
Why This Works
- Demonstrated nesting in the example is the strongest structural signal a prompt can send
- Item-level descriptions give arrays and objects the schema depth that type labels alone lack
- Uniform null discipline at every depth keeps deserializers from special-casing nested absence
Best for
- Schemas with tags, lists, or address-style sub-objects
- API responses where consumers index into nested paths
- Anyone whose arrays come back as "item1, item2" strings
Not for
- CSV destinations — flatten first or switch formats; the builder warns you
- Deeply recursive structures — beyond two levels, consider splitting the call
Use cases
- Stopping array fields from collapsing into comma-joined strings
- Keeping object fields nested instead of flattened into prefixed keys
- Defining item shapes so lists stay homogeneous across elements