Schema Evolution

An API's data structures rarely stay fixed. A response gains a field, an amount moves into a nested object, or an event acquires information that older records never contained. Updating the schema file is easy compared with keeping every reader and writer working through those changes.

Schema evolution is the controlled change of data definitions over time.

This chapter explains how to evolve fields, preserve their meaning, handle historical data, and verify mixed-schema interactions. The examples use a fictional order API, with a brief comparison between JSON and Protocol Buffers where their rules differ.