JSON Schema Explained: Validation, Examples & Common Errors

JSON is a data format; JSON Schema describes rules that a JSON value is expected to satisfy. A schema can state that a value must be an object, require certain keys, constrain a value to a set of choices, or define the expected type of a property. A validator compares the actual JSON with those rules and reports where the value does not conform.

This guide explains a practical workflow, shows a complete example, and clarifies what draft versions mean. The JSON Schema Validator can check a useful subset of common keywords locally. For full specification coverage, use a maintained validator in your application or test suite.

JSON syntax and schema rules are different checks

First, the data must be valid JSON. Property names and strings use double quotes, values are separated by commas, and comments and trailing commas are not allowed. The JSON Formatter can help make valid JSON easier to inspect, but formatting does not determine whether the structure matches a schema.

A schema check happens after parsing. For example, {"age":"36"} is syntactically valid JSON, but it does not satisfy a rule that expects age to be an integer. Keeping these two steps separate makes error messages easier to understand: a parser error means the text is not valid JSON, while a schema error means the parsed value violates a rule.

A small object schema

This example requires a person's name and age, restricts their types, and rejects undeclared fields:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "age"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 }
  },
  "additionalProperties": false
}

The type keyword applies to the whole value. required lists object keys that must be present. properties describes constraints for keys when they appear. Here, minimum prevents a negative age, and additionalProperties: false rejects keys that are not declared under properties.

A value that satisfies these rules is:

{
  "name": "Ada",
  "age": 36
}

This value is valid JSON but fails schema validation:

{
  "name": "Ada",
  "age": "36",
  "debug": true
}

There are two independent problems: age is a string instead of an integer, and debug is an undeclared property while extra properties are disabled. A validator may report both problems, with paths such as $.age and $.debug. Paths are useful because they identify the specific value, including nested values in larger documents.

Draft-07 and 2020-12

JSON Schema evolves through numbered drafts. Draft-07 and 2020-12 are two versions of the specification. They share many common keywords, including type, properties, required, and enum, but differ in vocabulary organization and the behavior and availability of some features. A schema's $schema property identifies the dialect it is written for; implementations use that identifier to select the corresponding rules.

Do not assume that every validator implements every draft or keyword. Tool Lockers' browser validator currently checks a limited shared set: type, required properties, property schemas, enum, const, string length and pattern, numeric bounds, array item limits and item schemas, and additional properties. It does not choose a full dialect based on $schema, resolve $ref, evaluate composition keywords such as oneOf, or implement every format and vocabulary. Treat its result as a check of that subset, not formal certification against the entire draft-07 or 2020-12 specification.

For production, choose a library that explicitly supports the draft and keywords used by your schema. Include representative valid and invalid samples in automated tests, and configure the validator consistently across your development, CI, and runtime environments.

Common validation errors

Missing required property. The schema lists a key in required, but the object does not contain it. Check spelling and capitalization; JSON property names are case-sensitive.

Type mismatch. The JSON value is not the expected type. A number written as "36" is a string because it is quoted. A value such as 36.5 is a number but not an integer.

Enum mismatch. The value is not equal to one of the allowed values. Verify exact spelling, capitalization, and JSON type; "1" and 1 are different values.

Unexpected property. When a schema disallows additional properties, each object key must be declared. Either correct a misspelled field or update the schema deliberately if the field is allowed.

Pattern mismatch. A string does not match the regular expression in pattern. Check anchors, escaping, required prefixes, and the exact string being validated. A pattern such as ^[A-Z]{3}-[0-9]{3}$ accepts ABC-123, but not abc-123 or ABC123.

A reliable validation workflow

Start with a small example and make the intended constraints explicit. Add required only for fields that truly must exist. Define each property's type and any meaningful bounds. Add additionalProperties: false when unknown fields should be rejected, but consider whether forward-compatible clients need to accept fields added later.

Run both valid and intentionally invalid examples. Confirm that accepted data represents the real application contract and that rejected data fails for the expected reason. When the validator reports several issues, fix one at a time and rerun it; an early type mismatch can hide deeper expectations in some implementations.

Keep schema versions and runtime validators aligned. If a schema uses references, custom formats, conditional keywords, or advanced composition, verify it with the same full-featured library that your application uses. A browser tool is useful for quick inspection, but automated tests and server-side validation should remain the source of truth for data that affects important operations.

Frequently asked questions

How do I validate JSON against a schema?

Parse the JSON, provide the schema and data to a validator, and inspect all reported paths. In the Tool Lockers validator, paste the schema and JSON into their editors and select Validate JSON.

What is the difference between draft-07 and 2020-12?

They are different specification versions with changes to vocabularies and some keyword behavior. Use a validator configured for the exact dialect and features in your schema.

Why does valid-looking JSON fail validation?

Valid JSON can still violate a schema. Check the failed path, required fields, types, enum values, patterns, and extra-property rules. Also confirm that the validator supports the keywords your schema relies on.