JSON Schema contracts

Select the dialect and validator before writing constraints. Verify the accepted data, not only the schema's syntax.

Establish the contract

Inspect existing schemas, validators, generator inputs, and producer and consumer versions.
Preserve the project's dialect unless migration is required. For new contracts, prefer Draft 2020-12 when all consumers support it.
Declare $schema explicitly. Use https://json-schema.org/draft/2020-12/schema for Draft 2020-12.
In Draft 2020-12, use $id for schema identity and $defs for reusable definitions.
Preserve older dialect keywords where required, including Draft 4 id and Draft 7 definitions.
Resolve relative $ref values against the applicable base URI. Verify every reference resolves in the deployed environment.
Distinguish standalone JSON Schema from a host specification's dialect, including OpenAPI Schema Objects.
OpenAPI 3.1 uses a dialect based on Draft 2020-12. Do not assume OpenAPI 3.0 schemas have the same semantics.