JSON Schema, explained for working developers

By ToolSura DevTools Team, Senior Engineers · View profile

What JSON Schema actually is

A JSON Schema is a JSON document that describes the shape, types, and constraints other JSON documents must satisfy. Where JSON defines how data is written, JSON Schema defines what data is acceptable: which fields exist, which are required, what types they carry, and what values count as valid. A schema is itself written in JSON, which means schemas can be validated by schemas, stored alongside code, and shipped wherever the data they govern travels.

The official getting-started guide builds a first working schema step by step, and every example below follows the same dialect.

The practical effect is a contract. Producers know exactly what they may emit, consumers know exactly what they may expect, and a validator enforces both directions without trust or guesswork.

A first schema with annotations

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 },
    "role": { "enum": ["admin", "editor", "viewer"] }
  },
  "required": ["email"]
}

This schema accepts objects with an email-shaped string (mandatory), an optional non-negative integer age, and an optional role limited to three values. Anything else fails validation with specifics about which constraint broke. The $schema line declares which dialect the document follows, currently draft 2020-12.

The core keywords worth knowing

Essential JSON Schema keywords

Keyword	Purpose	Example
type	Constrains the JSON type	"string", "integer", "array"
properties	Schemas for object fields	{"name": {"type": "string"}}
required	Mandatory field names	["email"]
items	Schema applied to array elements	{"type": "string"}
enum	Whitelist of exact values	["small", "large"]
format	Semantic string shapes	"email", "uri", "date-time"
$ref	Reference reusable $defs blocks	"#/$defs/address"

These seven keywords cover the large majority of real-world validation needs. Compositional keywords (allOf, anyOf, oneOf) layer on top when rules combine, and $defs keeps repeated structures like addresses in one place via $ref. The format reference catalogs every recognized shape from email to UUID.

Why teams bother with schemas

• API contracts: request and response bodies validated on both sides of the wire (OpenAPI builds exactly this pattern into API specifications), turning integration bugs into clear rejection messages
• Configuration safety: config files checked against schema at startup, catching typos before production does; our YAML versus JSON guide notes YAML configs convert to JSON for exactly this pass
• Documentation: a schema is executable documentation that cannot drift from reality the way prose docs do; the SchemaStore catalog distributes hundreds of ready-made schemas for popular config formats
• Code generation: tools like quicktype and datamodel-code-generator emit typed classes for mainstream languages, keeping types and contract in lockstep

A practical validation workflow

1. Draft the schema for your payload using the keywords above
2. Validate sample data against it during development; the online JSON schema validator checks samples without local setup
3. Wire validation into boundaries: API middleware, CI pipelines, or startup checks
4. Version the schema as payloads evolve so old consumers keep working while new fields arrive

The formatter step matters more than beginners expect: malformed JSON fails parsing before validation even begins, so run payloads through the JSON formatter first to separate syntax errors from contract violations.

How fast is validation in practice? On this machine, Python's jsonschema library checked 2,000 mixed user records against a schema with pattern, enum, and range constraints in 237 milliseconds, roughly 8,400 validations per second, with deliberately invalid records included in the batch. That is ample headroom for request-level API checks; high-throughput pipelines typically reach for compiled validators such as Ajv, which precompiles schemas into JavaScript functions before the first record arrives.

Schemas versus language types

TypeScript developers sometimes ask why schemas matter when static types exist. The two solve different halves of the problem: TypeScript proves your code matches types at compile time, but says nothing about the JSON arriving over the network at runtime. A schema validates the wire format where types cannot reach. Teams doing serious API work use both, generating types from schemas so the compile-time world and the wire contract stay synchronized. Our comparison of JSON Schema versus TypeScript types walks that division of labor in detail.

Common schema mistakes

Frequent JSON Schema mistakes

Mistake	Consequence	Fix
Forgetting required	Everything optional by default	List mandatory fields explicitly
Assuming extra fields fail validation	additionalProperties defaults to true	Set false on payloads that must stay closed
Using format expecting enforcement	Formats are annotations in most validators	Add regex or enable format-assertion mode
Duplicating nested structures	Drift between copies over time	Extract shared parts into $defs
Validating only happy-path samples	Gaps discovered in production	Test deliberately broken payloads too

Working with JSON Schema from here

A JSON Schema turns implicit expectations into explicit, machine-checkable contracts. Start small: pick one payload you care about, write its schema with the seven core keywords, validate real samples against it, and let the failure messages teach you the vocabulary. Within a week the habit spreads to every boundary where untrusted data enters your system, which is precisely where validation earns its keep.

Related Tools

• JSON Diff Compare
• JSON Schema Generator