Syntax validation proves that a response is JSON. Schema validation checks whether its structure and values match a contract. Used at the right boundaries, JSON Schema catches breaking changes early and produces more actionable diagnostics than a later undefined-property failure.

Begin with the smallest useful contract

Define the root type, required members and the types of fields consumed by the application. Add nested object and array schemas where the client depends on them. Avoid copying every accidental detail of a single sample into the first version.

Generated schemas are drafts. One example cannot reveal optionality, legal ranges, enum alternatives or whether additional properties should be accepted. Review each inferred rule against real producer behavior.

Be intentional about required and null

A required property must be present; it does not automatically have to be non-null. If a field can contain null, express that in its type. If it can be absent, omit it from required. Confusing absence with null is a common source of incompatible clients.

For evolving public APIs, allowing unknown object properties can make consumers more forward-compatible. For internal configuration or security-sensitive input, additionalProperties: false may be appropriate. Apply that constraint deliberately rather than mechanically everywhere.

Validate where failures are actionable

Producers should validate before sending or publishing a message. Consumers can validate at trust boundaries, in contract tests and in development diagnostics. Revalidating the same large document in every internal function adds cost without necessarily improving safety.

Capture the instance path, schema path and human-readable keyword message for failures. Do not log an entire production payload by default: the document may contain credentials or personal data.

Version schemas with the API

Store schemas alongside the code or interface definition they protect. Review schema changes like code changes, and run representative fixtures through both the old and new versions. A change that validates more inputs is not always harmless if consumers make narrower assumptions.

Use explicit identifiers and a consistent JSON Schema draft. Tooling behavior can differ across drafts, especially around references and unevaluated properties. Declaring the dialect makes validator configuration reproducible.

Practical takeaways

  • Schema generation is a starting point, not a full contract.
  • Required and nullable describe different conditions.
  • Choose additionalProperties behavior intentionally.
  • Report paths without exposing complete sensitive payloads.

How this guide was prepared

JSON Anvil guides are written for working developers, checked against reproducible examples, and reviewed for technical clarity. Tool output is tested locally; readers should still validate behavior in the exact runtime used by their application.