Version the meaning of a schema, not only its field names

Pin a dialect and a mapping version

Use a declared JSON Schema dialect, such as Draft 2020-12, together with an application mapping version. The dialect describes how schema keywords are interpreted. The mapping version describes how a provider payload becomes this publication’s normalized record. These are different versions and should not be compressed into one unexplained number.

A schema identifier should resolve to an immutable definition for a released integration. If the same URL quietly serves different rules, a historical validation result becomes hard to reproduce. Preserve the schema artifact and its digest with the fixture or data-run manifest, while keeping secret credentials out of that manifest.

A same-name semantic break

Imagine version 1 stores a synthetic value of 4.5 with unit percent. Version 2 changes the value to 0.045 but leaves the field named value. A consumer that divides by one hundred again produces 0.00045. The JSON type remains number throughout, yet the result is wrong by a factor of one hundred.

A safe migration would change the declared unit convention, document the conversion and test old and new consumers explicitly. Similarly, changing available_date from a retrieval date to an estimated publication date changes historical filtering behavior. That alteration needs an evidence review and a version change even if both values satisfy the same date format.

Choose an unknown-field policy

JSON Schema’s object rules let authors control required and additional properties. A strict normalized output contract can catch accidental misspellings such as retrievedAt when consumers expect retrieved_at. A provider-input parser may choose a different policy so that harmless upstream additions do not halt every ingestion run.

The distinction should be deliberate. Preserve unknown provider fields in a separate raw artifact where lawful and useful, with source_record locating the relevant item. Alert on changes to required fields or known meanings. Do not silently discard an unfamiliar field that might affect interpretation, such as a new revision status. Tolerance for extra structure is not permission to assume extra information is irrelevant.

Validate dates beyond their appearance

The Draft 2020-12 validation specification separates format annotation from optional assertion behavior. Therefore a date-time format label alone does not prove that a chosen validator enforces valid timestamps. Configure and test the validator’s actual behavior, and apply semantic date checks where required.

A synthetic 2026-02-30 string may match a simple digit-and-hyphen pattern but is not a valid calendar date. A timestamp without an offset may violate the application’s contract even if a permissive library parses it. Include these cases in compatibility tests so a validator upgrade cannot quietly change what the integration accepts.

Migrate with evidence and rollback

Create a fixture matrix covering supported provider shapes, nulls, malformed values, revisions, date precision and extra fields. Run both mapping versions and compare normalized records field by field. Expected differences need an explanation; unexpected differences should block adoption until understood.

Retain a way to replay the old version against the same raw fixture. A rollback should restore the former interpretation, not merely an older display. This workflow tests a bounded technical contract; it does not establish continued upstream availability or licensing. Provider changes can require both an adapter migration and a separate rights or evidence review.

Include one downstream consumer in the migration check. A new field accepted by the producer can still break an exporter with a fixed column list or a chart that expects a particular period convention.

Keep in the decision record

• Version units and time semantics as well as field structure.
• Test the validator’s actual format enforcement.
• Keep immutable fixtures and mappings for reproducible migration and rollback.

Source notes

1. JSON Schema Validation — Draft 2020-12
2. JSON Schema — Object reference
3. JSON Schema — String reference

Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.

Continue the analysis