JSON Schema Validator

JSON Schema: a vocabulary to validate JSON documents

JSON Schema is an IETF specification that lets you describe the structure, types and constraints of any JSON document using JSON itself. Born around 2010 as a community draft, it is today the de facto contract language for REST APIs, configuration files, message queues and SaaS plug-in systems. The canonical reference lives at json-schema.org.

A schema is a JSON object whose keywords describe what a valid document looks like: which keys are mandatory, what types each value can hold, whether strings match a regex, whether numbers fall inside a range and so on. A validator walks the schema and the document in parallel, emitting a verdict and a list of violations with JSON Pointer paths.

Spec drafts: from Draft 4 to 2020-12

JSON Schema has gone through several revisions, each backwards-incompatible in subtle ways. Knowing which draft a schema targets is critical:

• Draft 4 (legacy, 2013) — still common in older Swagger 2.0 / OpenAPI 2 toolchains; uses id and "required": ["x"] at root level.
• Draft 6 (2017) — introduced const, examples and renamed id to $id.
• Draft 7 (2018) — added if/then/else, readOnly/writeOnly and contentEncoding. Sweet spot of tooling maturity.
• Draft 2019-09 — split into vocabularies, replaced definitions with $defs and added unevaluatedProperties.
• Draft 2020-12 (current) — used by OpenAPI 3.1; reworked $ref resolution and tuple validation via prefixItems.

Always declare the dialect with $schema so validators pick the correct rules:

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

Core keywords every author should know

The keyword vocabulary is large, but a productive subset covers most cases:

• type — restricts to string, number, integer, boolean, array, object or null.
• properties + required — object shape and mandatory keys.
• minLength, maxLength, pattern — string constraints; pattern accepts ECMA-262 regex.
• minimum, maximum, exclusiveMinimum, multipleOf — numeric ranges.
• enum and const — closed sets of allowed values.
• oneOf, anyOf, allOf, not — logical combinators.
• format — semantic hints (email, uri, uuid, date-time); optional in 2020-12 unless a format-assertion vocabulary is enabled.
• $ref + $defs — reuse subschemas (avoid copy-paste).

Libraries and runtime performance

Implementations exist in every mainstream language:

• AJV (Node, TypeScript) — the most popular validator. Compiles the schema once to a specialized JavaScript function, reaching roughly one million validations per second.
• jsonschema and fastjsonschema (Python) — the first is interpreter-based; the second emits Python source for ~10x speed-ups.
• Everit JSON Schema and NetworkNT (Java) — production-grade for JVM stacks.
• jsonschema (Rust) and boon — high-performance native binaries.

For very hot paths, JIT-compiled validators such as AJV outperform hand-written if/else by a margin, because they specialize for the exact schema and skip dynamic dispatch.

Use cases beyond API contracts

• API request and response validation — OpenAPI 3.1 embeds JSON Schema 2020-12 for every payload.
• Configuration files — Kubernetes CRDs, GitHub Actions workflows and VS Code settings ship with JSON Schemas so editors autocomplete and warn.
• Form generation — react-jsonschema-form renders forms straight from a schema.
• Database validation — MongoDB (via JSON Schema validator) and Mongoose enforce shape on writes.
• Type generation — json-schema-to-typescript emits TS interfaces; quicktype targets dozens of languages.

JSON Schema vs Zod, Yup and TypeScript

Zod, Yup, io-ts and Valibot are TypeScript-first runtime validators; they bind tightly to TS types and offer ergonomic chained APIs. JSON Schema, by contrast, is language-agnostic and serializable: the same schema validates payloads in Node, Python, Go and Rust, and ships across the wire to clients. TypeScript types alone are compile-time only and disappear at runtime, so they cannot guard untrusted input. Many teams combine both: define the schema as JSON Schema, then derive TS types via json-schema-to-typescript.

Pitfalls and best practices

• Set additionalProperties: false when payloads should be strict — by default extra keys are silently accepted.
• Prefer $defs + $ref over duplication; reuse user, address and money shapes across endpoints.
• Use examples generously — they power Swagger UI sample payloads and contract-test fixtures.
• Pin the draft via $schema to avoid validator drift when AJV upgrades.
• Treat the validation error path as the API contract for clients (/users/0/email).

FAQ

Which validator is the best for Node?

AJV is the de facto choice — high performance, multi-draft support, TypeScript types and a healthy ecosystem (Fastify, ESLint, NestJS all rely on it).

How is JSON Schema different from TypeScript types?

TypeScript checks at compile time only; the types vanish at runtime. JSON Schema runs at runtime and is therefore the right tool to validate untrusted input (HTTP bodies, config files, queue messages).

Can I reuse subschemas across files?

Yes. Define them under $defs and reference with $ref, locally (#/$defs/User) or remotely (https://api.example.com/schemas/user.json). AJV can preload remote schemas via addSchema().

Does OpenAPI 3.1 use JSON Schema?

Yes — OpenAPI 3.1 fully aligns with JSON Schema Draft 2020-12. Earlier OpenAPI 3.0 used a subset that diverged in small but irritating ways (nullable, integer formats).

Why does my schema not reject extra fields?

Because additionalProperties defaults to true. Set it to false (or to a schema) on every object you want sealed.