JSON Schema Basics: Validating Structure

There are two different questions you can ask about a JSON document. The first is "does it parse?" — is the syntax correct, with matching brackets and proper quotes. The second is "is it the right shape?" — does it contain the fields your program expects, with the right types and sensible values. A formatter answers the first question; JSON Schema answers the second.

A JSON Schema is itself a JSON document. It declares the expected type of each value with keywords like "type": "object" or "type": "string", lists which properties are required, and can constrain values — a minimum and maximum for numbers, a pattern for strings, or an enumerated set of allowed options. You can also nest schemas so that each element of an array, or each property of an object, follows its own rules.

Because the schema is machine-readable, a validator can compare any document against it and report exactly which rule failed and where — far more useful than a vague "invalid input" message.

A minimal schema for a user record reads almost like prose. "$schema" names the dialect you are writing against; "type": "object" says the document must be an object; "properties" maps each key to its own sub-schema — "name" with "type": "string" and "minLength": 1, "age" with "type": "integer" and "minimum": 0; and "required": ["name"] lists the keys that must be present. Everything the schema does not mention is allowed by default.

That default surprises people: a schema describes constraints, not a closed list, so unknown properties pass unless you say otherwise. Adding "additionalProperties": false rejects anything you did not describe, which catches typos like "emial" that would otherwise slip through in silence. Similar keywords exist for the other types: "items" for the shape of array elements, "minItems" and "uniqueItems" for the array itself, "pattern" for a regular expression on a string, and "enum" for a fixed set of allowed values.

JSON Schema has evolved through several drafts, and the differences matter when you pick a validator. Draft-07 is still the most widely deployed; 2019-09 and 2020-12 are the current line and changed how array items and references are expressed. Declare the dialect explicitly with "$schema" so that humans and tools both know which rules apply, and check that your validator — Ajv in JavaScript, python-jsonschema, or everit and networknt on the JVM — supports it.

Large schemas stay manageable through references. Define a shared shape once under "$defs" and point at it with "$ref": "#/$defs/address", or reference a schema hosted at a URL to share it across services. OpenAPI descriptions use the same mechanism, which is why an API's request and response schemas can often be reused directly both for runtime validation and for generating client types.

Schemas shine at the boundaries of a system. An API can validate incoming requests against a schema and reject malformed ones before they reach business logic. A configuration file can be checked on startup so a typo fails loudly instead of causing a strange bug later. Editors use schemas to offer autocomplete and inline warnings as you type. In each case the schema turns a class of runtime surprises into an immediate, precise error.

Before you write or apply a schema, it helps to see your data clearly. Format a sample document here and expand its tree to inventory the keys and types you will need to describe.

Schemas describe shape, not business rules. They can say that a start date and an end date are both ISO strings, but not that the second must fall after the first. Conditional keywords stretch a little further — "if", "then", "else" and "dependentRequired" can demand a VAT number whenever the country is an EU member — yet past a certain point the rules belong in code, where they can be tested, named and explained.

The other limit is trust. A schema validates structure at the boundary; it does not sanitise values, enforce authorisation or guarantee that a well-shaped request is a legitimate one. Treat it as the first filter in a chain: reject the malformed early and cheaply, then apply the checks that need context.