Schema Versioning and Validation

JSON Schema has draft versions. A draft defines which keywords exist and how validators should interpret them. Modern schemas often use Draft 2020-12, while older ecosystems may still expect Draft 7.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The $schema field tells tools which dialect to use. Pick a draft that your validators, editors, and API tooling support.

Validation errors are part of the contract

A useful schema fails with errors that point to the problem:

• Missing required property
• Wrong type
• Value below minimum
• String that does not match a format
• Extra property rejected by policy

When you review a schema, test both valid and invalid examples. Invalid fixtures are often more valuable because they prove the validator catches mistakes you care about.

Compatibility rules

Changing a schema can break clients. Treat schema evolution like API evolution:

• Adding an optional property is usually safe.
• Adding a required property can break existing producers.
• Narrowing an enum can break stored data and clients.
• Changing a type is usually a breaking change.
• Removing a field can break consumers.

Draft choice in practice

Draft 2020-12 is a sensible default for new local workflows. Draft 7 remains useful when older tools require it. The best draft is the newest one that your production validator actually supports.

Schemas are living contracts. Keep them close to examples, tests, and release notes so the data contract evolves with the system instead of drifting away from it.