# Schema versioning

Payload schemas and API transport versions are separate contracts.

## Payload versions
Read schema_version where the dataset or feed includes it. The standard collector feed convention bumps schema_version on breaking shape changes. Do not assume every endpoint has the same envelope; the OpenAPI operation describes that endpoint.

## Research transport
Research and MCP expose X-Api-Version. Their deprecation policy uses Deprecation and Sunset headers when a retirement is announced. See [changelog and deprecation](/docs/resources/changelog).

## Client behavior
Ignore additive unknown fields, validate required fields, preserve null and distinguish an empty successful page from an error. Re-check the OpenAPI document when a schema or API version changes.