JSON Schema validation turns an unclear “bad request” response into a specific explanation of what is wrong with a payload. This guide shows how to validate JSON against a schema, interpret failures involving required fields, types, formats, arrays, and nested objects, and compare browser-based tools with command-line, library, IDE, and API-contract workflows.
Overview
JSON syntax validation and JSON Schema validation are related but different checks. A syntax check confirms that a document is valid JSON: braces are balanced, strings are quoted, and values use valid JSON notation. A schema check goes further by testing whether the document has the expected structure and values.
A schema can define required properties, permitted data types, minimum and maximum values, string patterns, formats, array contents, nested objects, and whether unknown properties are allowed. For example, this schema describes a small API request:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["email", "age"],
"properties": {
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 18 },
"roles": {
"type": "array",
"items": { "type": "string" }
}
},
"additionalProperties": false
}
A payload is valid only when it satisfies every applicable rule. In this example, a missing email, a decimal age, a value below 18, or an unexpected property can each cause validation to fail. A useful JSON Schema validator should report the path to the failing value, the violated keyword, and enough detail to fix the payload.
How to compare options
The best JSON Schema validator depends on where validation belongs in your workflow. Compare tools by the job they perform, not simply by whether they display a green success message.
- Draft support: Check which JSON Schema dialects and drafts the validator understands. A schema may behave differently when a tool does not support the draft or vocabulary it declares.
- Error detail: Prefer results that identify an instance path such as
/customer/email, the failed keyword, and the expected value or type. Aggregated errors are more useful than a single generic failure. - Format behavior: Determine whether formats such as
email,date, anduriare enforced, treated as annotations, or controlled by an option. Do not assume two validators apply format rules identically. - Security and privacy: Avoid pasting credentials, access tokens, customer data, or production secrets into an online validator. For sensitive payloads, use a local CLI, library, or approved internal tool.
- Automation: For repeatable checks, choose a validator that runs in tests or CI and returns a reliable exit status. A browser-based tool is useful for investigation but should not be the only gate for an API contract.
- Schema management: Look for support for references, reusable definitions, multiple files, and the way your team stores schemas. Complex contracts quickly exceed the convenience of a one-off paste-and-check workflow.
- Output and integration: Consider machine-readable errors, source locations, custom messages, and compatibility with your test runner or API tooling.
A practical comparison usually includes four categories: a browser-based validator for fast, no-setup inspection; a CLI or library for local and automated checks; an IDE extension for feedback while editing; and an OpenAPI-aware validator when the schema is part of an HTTP request or response contract. These options complement one another rather than forming a single universal ranking.
Feature-by-feature breakdown
Required properties
The required keyword applies to object properties. If a schema requires email and the payload omits it, the fix is to add the property or revise the schema if it is not truly mandatory. An empty string is still present; whether it is acceptable requires a separate rule such as minLength.
Types and null values
JSON Schema distinguishes strings, numbers, integers, booleans, arrays, objects, and null. A value of "42" is a string, not a number, even if an application could convert it. Likewise, null does not automatically satisfy a string or object rule. If null is intentional, model it explicitly with the schema dialect and validator behavior used by your project.
Formats and patterns
Formats communicate expectations for values such as dates, times, email addresses, and URIs. Validate the same way in development, CI, and production because format enforcement can be configurable. Use pattern for a regular-expression constraint when a format alone is not precise enough, and document the expected form for API consumers.
Arrays and nested objects
For arrays, inspect both the array itself and its items rule. A payload can contain a valid array with invalid elements, such as a number where each item must be a string. For nested objects, follow the reported path from the root and check the nearest object schema. Errors several levels deep are easier to resolve when the validator preserves paths rather than flattening them into prose.
Additional properties
additionalProperties: false catches misspelled or undocumented fields, which can be valuable for strict internal contracts. It can also make evolution harder if clients send harmless extensions. Decide deliberately whether unknown fields should be rejected, ignored, or permitted, and apply that decision consistently across related schemas.
References and draft compatibility
Reusable schemas commonly rely on references. If a validator reports an unresolved reference, check the base URI, file loading rules, and whether referenced schemas are available in the selected environment. Also verify the declared draft before comparing results between tools. A difference may reflect unsupported keywords or dialect semantics rather than a malformed payload.
| Validation error | Likely cause | Useful next step |
|---|---|---|
| Required property missing | Field is absent from the object | Add it, or confirm that the schema should require it |
| Type mismatch | String, number, integer, or null used incorrectly | Inspect the raw JSON value; do not rely on visual appearance |
| Format failure | Value does not meet the validator's format rule | Check format configuration and normalize the value |
| Array item failure | One or more elements violate items | Use the element index in the error path to find the bad item |
| Additional property | Unexpected or misspelled field | Correct the name, remove the field, or revise the extension policy |
Best fit by scenario
Quick API response inspection: Use a browser-based JSON Schema validator when you need to compare a captured response with a schema without installing software. First remove secrets and personal data, then record the schema draft and validation settings alongside the result.
Request and response tests: Use a library or CLI in unit, integration, or contract tests. Validate representative success cases, boundary values, missing fields, wrong types, and unknown properties. This catches regressions that manual inspection will miss.
OpenAPI contracts: Use an OpenAPI-aware workflow when the schema is embedded in endpoint definitions. Validate method, path, headers, status code, and content type as well as the JSON body. A payload can satisfy its body schema and still fail the broader HTTP contract.
Fixture and event validation: Run validation against stored fixtures before they enter a test suite, queue, or data pipeline. Keep fixtures that represent both valid and intentionally invalid cases so error handling remains tested.
Schema evolution: Compare old and new schemas against existing payload examples. Pay special attention to newly required fields, narrowed types, stricter enums, disabled additional properties, and changes to nullability. A change that validates new data may still break existing consumers.
For related API troubleshooting, pair schema results with an OpenAPI validation workflow and the HTTP status code debugging matrix. When the body is delivered by a webhook, also check signatures, retries, and transport failures using the webhook debugging guide.
When to revisit
Revisit this validation workflow whenever an API payload, schema draft, validator library, or contract-testing tool changes. An annual review is also useful for confirming that the selected validator still supports the drafts, keywords, formats, and reference patterns your team uses. Recheck behavior when a tool changes its format defaults, error output, browser processing model, or supported integrations.
Use this short process during the next schema change:
- Confirm the schema draft and validator configuration.
- Validate a known-good payload and save the result as a baseline.
- Validate a deliberately broken payload for each changed rule.
- Read the instance path, keyword, and expected value before editing the payload.
- Run the same cases locally and in CI to detect configuration differences.
- Review compatibility with existing clients, fixtures, and OpenAPI definitions.
- Remove sensitive data from examples and document any intentional strictness.
For quick formatting and adjacent checks, a compact browser developer tools workflow can help prepare payloads before validation. For repeatable transformations and command-line inspection, see the jq guide. The goal is not merely to make one payload pass; it is to make the contract understandable, testable, and safe to change.