Saved data outlives the code that wrote it. A version field lets a loader distinguish older shapes from current ones. A migration should preserve unknown fields where possible, avoid mutating the original and reject future versions that it does not understand. Applying the migration to an already-current record should be harmless.

record = {"version": 1, "name": "Ada"}
copy = dict(record)
copy["version"] = 2
print(record["version"])

Version-directed migration makes the compatibility contract explicit. Copying protects the caller's data, and preserving unrelated fields prevents accidental loss during a narrow schema change. Work through the example by hand before changing the starter. Decide what should happen for an empty input, a single value and a repeated value where those cases apply. The checks use several inputs so a hard-coded answer cannot stand in for the rule.

Write upgrade(record). Missing version means 1. Version 1 renames name to display_name (default ""), removes name and sets version to 2. Version 2 returns a shallow copy unchanged. Preserve all other fields. Reject every other version with ValueError.

The explanation opens here once every check passes.