How to Validate JSON Against a Schema

JSON Schema defines the structure, types, and constraints that a JSON document must follow. Instead of discovering data issues at runtime, the JSON Schema Validator catches problems before you ship — wrong types, missing required fields, values outside allowed ranges, and pattern mismatches are all reported with precise error paths.

Understanding JSON Schema validation

JSON Schema is a vocabulary for describing the shape of JSON data. A schema specifies which fields are required, what types they should be, what values are acceptable, and how nested objects and arrays should be structured. When you validate a JSON document against a schema, the validator checks every constraint and reports all violations.

Schemas use keywords like type, required, properties, items, minimum, maximum, pattern, enum, and format to express constraints. For example, {"type": "string", "minLength": 1} ensures a value is a non-empty string. {"type": "array", "items": {"type": "number"}} ensures an array contains only numbers.

Schemas can be composed using $ref to reference other schemas, and combined using allOf, anyOf, oneOf, and not for complex validation logic. This allows you to build reusable schema libraries for your organization’s data models.

Tips and best practices

• Start with a simple schema and add constraints. Define required fields and types first, then add format validations, ranges, and pattern checks incrementally.
• Use additionalProperties: false to catch typos. This rejects any JSON keys not explicitly defined in the schema, which catches misspelled field names that would otherwise be silently ignored.
• Test with both valid and invalid data. A schema that accepts everything is useless. Verify your schema rejects data that should be invalid, not just that it accepts good data.
• Use $ref for reusable definitions. If the same sub-schema appears in multiple places (like an address object), define it once in $defs and reference it with $ref.
• Pin your schema draft version. Include "$schema": "https://json-schema.org/draft/2020-12/schema" to specify which draft the schema uses. Different drafts have different keyword behavior.

Common issues

• Schema validates but does not catch errors you expect. The most common cause is forgetting to include fields in the required array. In JSON Schema, properties are optional by default.
• additionalProperties conflicts with allOf. When composing schemas with allOf, additionalProperties applies only to the schema where it is defined, not to properties from referenced schemas. Use unevaluatedProperties in draft 2019-09+ instead.
• Format validation not enforced. The format keyword (for values like "email" or "date-time") is an annotation by default in recent drafts and may not be validated unless explicitly enabled. Check your validator’s configuration.