Schema Evolution

Core rule

A schema change is a compatibility event even when the code diff is small.

Define old and new shapes, defaults for added fields, treatment of unknown fields, and whether readers/writers remain backward compatible. Provide a versioned migration when persisted data cannot be read directly.

Test at least: current writer→current reader, previous supported writer→current reader, current writer→older consumer when backward output is promised, missing optional fields, unknown future fields, and malformed input.

Preserve user-owned unknown data when round-tripping configs unless the schema explicitly forbids it. Never silently reinterpret an old field with a new meaning; migrate deliberately and record the schema version used.