JSON Schema Validation Guide: Check API Payloads, Required Fields, Types, and Compatibility
JSONJSON SchemaAPIsvalidationtestingdeveloper tools

JSON Schema Validation Guide: Check API Payloads, Required Fields, Types, and Compatibility

TToggle Editorial Team
2026-11-17
7 min read

Learn how to validate JSON against a schema, diagnose exact failures, compare tools, and manage API contract compatibility.

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, and uri are 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 errorLikely causeUseful next step
Required property missingField is absent from the objectAdd it, or confirm that the schema should require it
Type mismatchString, number, integer, or null used incorrectlyInspect the raw JSON value; do not rely on visual appearance
Format failureValue does not meet the validator's format ruleCheck format configuration and normalize the value
Array item failureOne or more elements violate itemsUse the element index in the error path to find the bad item
Additional propertyUnexpected or misspelled fieldCorrect 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:

  1. Confirm the schema draft and validator configuration.
  2. Validate a known-good payload and save the result as a baseline.
  3. Validate a deliberately broken payload for each changed rule.
  4. Read the instance path, keyword, and expected value before editing the payload.
  5. Run the same cases locally and in CI to detect configuration differences.
  6. Review compatibility with existing clients, fixtures, and OpenAPI definitions.
  7. 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.

Related Topics

#JSON#JSON Schema#APIs#validation#testing#developer tools
T

Toggle Editorial Team

Developer Tools Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.