Home/
Part XIII — Expert Mode: Systems, Agents, and Automation/40. Advanced Structured Output/40.3 Schema evolution and backwards compatibility
40.3 Schema evolution and backwards compatibility
Overview and links for this section of the guide.
On this page
Evolution Rules
Schemas change over time. Follow these rules for backwards compatibility:
| Safe Changes | Breaking Changes |
|---|---|
| Add optional field | Add required field |
| Add enum value | Remove enum value |
| Widen type (int → number) | Narrow type |
| Make required → optional | Make optional → required |
Versioning Strategies
// Strategy 1: Version in field
{ "version": "2.0", "data": { ... } }
// Strategy 2: Version in accept header
const response = await generate({
headers: { 'Accept': 'application/vnd.api+json;version=2' }
});
// Strategy 3: Graceful defaults
const ResponseV2 = z.object({
id: z.string(),
newField: z.string().optional().default('default_value')
});