Make object boundaries explicit

Start at every object boundary and decide whether unrecognized properties are accepted. An omitted additionalProperties rule can make a contract appear stricter than the validator actually enforces, which becomes especially confusing when producers and consumers deploy at different times.

Document required fields separately from fields that are merely described. A property declaration does not make that property required, so reviewers should compare the properties map with the required array at every nested level.

  • Confirm the intended behavior for unknown keys at the root and inside nested objects.
  • Check that each business-critical property appears in the correct required array.

Test representative payloads

A schema can be syntactically valid and still fail to express the intended contract. Validate known-good examples, boundary values, and intentionally broken payloads so that the expected acceptance and rejection behavior is visible before deployment.

Keep examples close to the contract and rerun them whenever the schema changes. Stable fixtures turn a vague review into a reproducible check and help teams identify whether a producer, consumer, or schema revision introduced the difference.

  • Include missing required values, wrong primitive types, empty collections, and extra properties.
  • Fingerprint the reviewed schema so later reports can be tied to the exact contract version.

Treat composition as a review hotspot

Keywords such as oneOf, anyOf, and allOf are powerful, but overlapping branches can make successful validation mean something different from what a reviewer expects. Test values that match no branch, exactly one branch, and more than one branch so ambiguity becomes a deliberate choice rather than a production surprise.

When a contract grows through references and composition, review the resolved behavior rather than only the top-level file. The useful question is whether a real payload is accepted for the intended reason and rejected with a diagnostic that an operator can act on.

  • Check whether oneOf branches are mutually exclusive for representative payloads.
  • Resolve local and remote references in the same environment used by the deployed validator.