2 min readMay 17, 2026Updated 2026-10-10

JSON Schema Validation Explained

Understand how JSON Schema describes payload shape, required fields, types, arrays, objects, and practical API validation limits.

Maintained by Ali Aygör. Report a correction.

Open JSON Schema Validator & Generator Open JSON Validator

Separate JSON syntax from its contract

JSON Validator answers whether a document can be parsed. JSON Schema answers whether the parsed instance satisfies specified constraints. A valid JSON object can still have a missing property, wrong type, extra field or disallowed value.

Choose a draft explicitly and validate against the contract used by your API. This site's combined validator uses draft 2020-12 and a real schema validation engine rather than only checking a few top-level types.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "roles"],
  "properties": {
    "id": {"type": "integer", "minimum": 1},
    "roles": {"type": "array", "items": {"enum": ["reader", "editor"]}}
  },
  "additionalProperties": false
}

Test a passing instance and deliberate failures

Start with {"id":1,"roles":["reader"]}. Then change one condition at a time: remove id, use 1.5, use the string "1", add an unknown role and add an extra property. Each failure should lead to a relevant instance location or rule.

This makes the test useful: a positive sample alone cannot show that the validator enforces constraints. Keep each negative fixture and its expected failure with your contract tests.

{"id":1,"roles":["reader"]}                 // passes
{"id":1.5,"roles":["reader"]}               // integer fails
{"id":1,"roles":["admin"]}                  // enum fails
{"id":1,"roles":[],"unexpected":true}       // extra property fails

Presence, null and empty are separate decisions

required checks property presence. It does not automatically prohibit null or an empty string; use type and length constraints to express those decisions. Similarly, an empty array can pass an items rule unless a minimum item count is specified.

Review these distinctions with the client teams. A contract that accidentally treats absent and null as equivalent can hide a compatibility change even when both examples look reasonable to a human.

Generated schemas need editing

Inference describes observed values, not all valid domain states. A field present in one example is not necessarily required. A single array element cannot establish every allowed item shape, so test mixed values and object variants.

The generator now considers all observed array elements and retains variant shapes. Review generated required fields and additional-property policy before publishing the schema. Add optional properties, enum rules and ranges from the actual contract rather than guessing from sample data.

Keep business validation separate

A schema can validate a representation but cannot establish that a user owns an order, a product is purchasable or a state transition is allowed. Apply authorization and domain rules in the application and test them independently.

Local references can connect schemas within the supplied document. External references are not downloaded here. If your production schema uses separate documents, verify it with the same registry and validator configuration used by the API.