What Is a JSON Schema? Validating JSON Documents

A JSON Schema is a JSON document that describes the structure, allowed types, and constraints of other JSON data, giving you a machine-readable contract you can validate against and use as documentation. Instead of hand-writing checks for every field, you declare the rules once, and a validator confirms that a given JSON document conforms. JSON Schema is maintained as an evolving specification with several published drafts, and it powers API request validation, configuration checking, form generation, and code generation across many ecosystems.

Key takeaways

• A JSON Schema is itself valid JSON, so it is portable and easy to store and share.
• Core keywords include type, properties, required, items, and enum.
• $schema declares the draft dialect; $id and $ref enable identification and reuse.
• By default extra properties are allowed; set additionalProperties to false to forbid them.
• Drafts such as draft-07, 2019-09, and 2020-12 differ subtly, so match your validator to your declared draft.
• format validation (email, date-time) is often optional and must be enabled explicitly.

What problem does JSON Schema solve?

Without a schema, every consumer of a JSON payload must reimplement its own ad-hoc validation, and those checks inevitably drift apart. JSON Schema centralizes the rules into one authoritative document. A validator then answers a single question: does this data conform to this schema? That gives you three benefits at once.

• Validation: reject malformed input at the boundary of your system.
• Documentation: the schema is a precise, always-current description of the data shape.
• Tooling: editors, form builders, and code generators can consume the schema to provide autocompletion, UI, and typed models.

What does a basic JSON Schema look like?

Here is a schema describing a simple user object. Every keyword is a normal JSON property.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["id", "name"],
  "additionalProperties": false
}

This schema requires an integer id and a non-empty name, optionally accepts an email and an array of string roles, and forbids any property not listed.

What are the core keywords I should know?

Keywords fall into a few groups: type declarations, object constraints, array constraints, and value constraints.

How do type, properties, and required interact?

These three keywords are the most misunderstood. type says what kind of value is allowed at this position. properties attaches a subschema to each named member of an object, but only constrains a property when it is actually present. required is what forces a property to exist.

The practical consequence is that defining a property under properties does not make it mandatory. A schema that lists email in properties but not in required will happily validate an object with no email at all. To make a field mandatory you must name it in required.

Why does additionalProperties matter for security?

By default JSON Schema is permissive: an object may carry any number of properties you never mentioned, and they all pass. That is convenient for forward compatibility but risky at a trust boundary, because a caller can smuggle unexpected fields into your system.

Set additionalProperties to false when you want a strict, closed object that rejects anything unlisted. This is especially valuable for request validation, where accepting stray fields can lead to mass-assignment style bugs. Be aware that a strict setting also breaks forward compatibility, so weigh strictness against the need to add fields later without breaking old clients.

What are $schema, $id, and $ref for?

These keywords manage dialect and reuse:

• $schema names the draft your document targets so a validator applies the right keyword meanings. Declaring it explicitly avoids the validator guessing.
• $id assigns a base identifier to a schema, which anchors relative references and lets other schemas point at it.
• $ref references another schema or a subschema, enabling you to define a shape once and reuse it. References commonly point into a reusable-definitions section, called $defs in recent drafts.

{
  "$defs": {
    "nonEmptyString": { "type": "string", "minLength": 1 }
  },
  "type": "object",
  "properties": {
    "title": { "$ref": "#/$defs/nonEmptyString" }
  }
}

Which JSON Schema draft should I use?

The specification has evolved through several drafts, and they are mostly compatible but not identical. draft-07 remains extremely common because of broad tooling support; draft 2019-09 and draft 2020-12 introduced refinements, including changes to how array items and reusable definitions are expressed. The critical rule is consistency: your $schema declaration and your validator must agree on the dialect, or keywords may be interpreted differently or silently ignored. Do not mix keyword syntax from different drafts in one document.

Does JSON Schema validate string formats?

The format keyword names semantic formats such as email, date-time, uri, and uuid. However, in several drafts format is treated as an annotation by default rather than a hard assertion, meaning a validator may accept a value that violates the format unless you explicitly turn on format checking. If you rely on format enforcement, confirm your validator has format assertion enabled, or add a pattern as a backstop for critical fields.

What are common JSON Schema pitfalls?

1. Assuming defined equals required. Always add mandatory fields to required.
2. Forgetting additionalProperties. Open objects accept unexpected data unless closed.
3. Mismatched draft and validator. Declare $schema and use a matching validator.
4. Expecting format to always fail invalid values. Enable format assertion when it must be enforced.
5. Confusing integer and number. integer rejects fractional values; number accepts them.

Frequently asked questions

Is JSON Schema itself written in JSON?

Yes. A JSON Schema is a JSON document whose keywords describe the shape and constraints of other JSON data, so schemas can be stored, transmitted, and validated like any other JSON.

What does the $schema keyword do?

It declares which draft of the JSON Schema specification the document targets, so validators apply the correct keyword semantics. Omitting it forces the validator to assume a default dialect.

Are additional properties allowed by default?

Yes. Unless you set additionalProperties to false or constrain them, an object may contain properties beyond those you listed, and they pass validation.

What is the difference between properties and required?

properties defines the schema for each named property if it appears, while required lists which property names must be present. A property can be defined without being required.

What are the main JSON Schema drafts?

Widely used drafts include draft-07, draft 2019-09, and draft 2020-12. They are mostly compatible but differ in some keywords, so match your validator to your $schema.

How do I reuse parts of a schema?

Define reusable subschemas and reference them with $ref, typically pointing into a definitions section such as $defs, which keeps large schemas DRY and readable.

Does JSON Schema validate formats like email or date?

The format keyword names formats such as email and date-time, but format assertion is optional in several drafts. Enable format validation explicitly if you need it enforced.