JSON Schema
JSON Schema is a separate specification for describing the structure and constraints JSON data should follow. Learn what it validates, its core keywords, and how it differs from JSON itself.
Try It Now
Put this into practice with OpenFormatter's free tools — no signup, 100% client-side.
Specification: JSON Schema is not an IETF RFC. Despite the JSON format itself being defined by RFC 8259, JSON Schema is specified and published independently by the JSON Schema organization through its own versioned drafts, not through the IETF RFC process. The two specifications share no formal relationship beyond one describing documents written in the other.
Important: `additionalProperties` is not false by default. Unless a schema explicitly sets `"additionalProperties": false`, extra fields not listed in `properties` are allowed to pass validation. Developers expecting strict-by-default validation are often surprised an instance with unexpected fields still validates successfully.
Definition
JSON Schema is a separate specification — not part of RFC 8259, and not an IETF RFC itself — for describing the structure and constraints a JSON document should satisfy. Where JSON's own grammar (see JSON Syntax) only answers "is this text well-formed JSON," JSON Schema answers a different question: "does this specific document have the shape I expect?" A document can pass the first check and fail the second — RFC 8259 has no concept of a required field, but a schema can demand one.
A schema is itself written as JSON. The document being checked against a schema is called an instance. JSON Schema is independently maintained and published by the JSON Schema organization — currently at version 2020-12 (previously 2019-09), with the first proposal dating back to 2007 — on its own release cadence, unconnected to RFC 8259's.
Examples
A minimal schema — requires the instance to be an object, nothing more.
{ "type": "object" }A schema combining type, properties, and required.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" }
},
"required": ["name", "email"]
}A schema validating a nested object — the same pricing shape used as an example on the JSON Objects page.
{
"type": "object",
"properties": {
"id": { "type": "number" },
"name": { "type": "string" },
"pricing": {
"type": "object",
"properties": {
"free": { "type": "boolean" },
"plans": { "type": "array", "items": { "type": "string" } }
},
"required": ["free", "plans"]
}
},
"required": ["id", "name", "pricing"]
}| Keyword | Purpose | Example |
|---|---|---|
| type | Restricts the instance to a JSON type | "type": "object" |
| properties | Defines a sub-schema for each named property | "properties": { "name": { "type": "string" } } |
| required | Array of property names that must be present | "required": ["name", "email"] |
| additionalProperties | Controls whether properties outside "properties" are allowed | "additionalProperties": false |
Common Mistakes
Assuming syntactically valid JSON automatically satisfies a schema
RFC 8259 syntax validity and JSON Schema validation check completely different things — a document can parse without error and still be missing required fields, have the wrong types, or include values a schema explicitly rejects.
Fix: Validate the parsed instance against its schema explicitly. A successful JSON.parse() call says nothing about whether the resulting data has the shape your program expects.