JSON Schema validation turns an informal API payload into a testable contract. This checklist explains how to choose a JSON Schema validator online or in a project, create a schema from an example response, test required fields and defaults, interpret path-based errors, and add repeatable checks to development and CI workflows.
Overview
Valid JSON is not necessarily correct JSON. A document can have perfect syntax while using the wrong data types, omitting a required property, or including a value outside the API contract. JSON Schema addresses those problems by describing the structure and constraints a JSON document should follow.
A schema can define object properties, required fields, arrays, allowed values, string patterns, numeric limits, and nested structures. It can be used to validate request bodies before they reach an API, check response fixtures during testing, or protect a data-processing script from unexpected input.
The right validation tool depends on what you are checking. A browser-based JSON Schema validator is convenient for a quick payload review, while an editor extension is useful during authoring. A command-line validator or application library is more suitable for repeatable checks in a repository and continuous integration. Before choosing a tool, confirm the JSON Schema draft and validator version it supports; syntax and behavior can vary between implementations.
For related formatting and data-handling tasks, see the JSON Formatter and Validator Guide or compare complementary utilities in the Online Data-Handling Toolbox.
| Tool type | Best for | Check before relying on it |
|---|---|---|
| Browser validator | One-off payload and schema checks | Privacy handling, size limits, draft support, and whether data is processed locally |
| Editor extension | Feedback while writing JSON | Workspace settings, schema association, and error detail |
| Command-line tool | Scripts, fixtures, and CI checks | Installation method, exit codes, draft support, and reproducible configuration |
| Application library | Runtime request or response validation | Version compatibility, error handling, performance, and how defaults are treated |
Checklist by scenario
When validating a payload online
- Remove sensitive values. Replace tokens, personal information, credentials, and production identifiers with safe placeholders before pasting data into a browser tool. If privacy matters, prefer a local validator or confirm that processing occurs in the browser.
- Format the JSON first. A formatter makes nesting, commas, arrays, and duplicate-looking properties easier to inspect. Syntax validation and schema validation are separate steps.
- Load the schema and payload separately. Do not confuse a schema document with an example instance. The schema describes what is allowed; the payload is the document being tested.
- Check the reported path. An error such as
/customer/contact/emailpoints to a nested location. Start there rather than scanning the entire document. - Record the tool configuration. Note the draft, format settings, and relevant options if the result will be used to diagnose an API issue.
When turning an example response into a schema
Start with a representative example, but treat generated output as a draft rather than a finished contract. For a response such as:
{
"id": "usr_123",
"displayName": "Avery",
"active": true,
"roles": ["reader"]
}
you might refine the structure into:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": { "type": "string" },
"displayName": { "type": "string" },
"active": { "type": "boolean" },
"roles": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["id", "displayName", "active", "roles"],
"additionalProperties": false
}
Decide deliberately which properties are required. An example containing one field does not prove that the field is always present. Likewise, an array with one string does not reveal whether other item types are permitted. Compare several real or representative examples before tightening constraints such as additionalProperties, string patterns, or enumerated values.
When testing request and response contracts
- Keep request and response schemas separate when their fields or required values differ.
- Test at least one valid payload that represents normal usage.
- Test missing required properties, incorrect types, empty arrays, unexpected enum values, and malformed nested objects.
- Include boundary values for numbers, string lengths, and array sizes when those limits matter.
- Check both successful validation and useful failure reporting. A validator that rejects bad data but provides no actionable path can slow debugging.
For broader API troubleshooting, pair schema checks with the request inspection techniques in the API Debugging Tools guide. Schema validation will not diagnose every transport, authentication, or CORS problem.
When adding validation to a project
- Store schemas beside the API specification, fixtures, or versioned contract files.
- Choose one validator configuration for local development and CI where possible.
- Validate representative fixtures as part of the test command.
- Make failures return a non-success status so CI can stop when a contract breaks.
- Print the instance path, schema path, keyword, and message for each failure.
- Review intentional breaking changes with the consumers of the contract.
Command examples differ by language, package, and validator, so copy the syntax from the selected tool's current documentation rather than assuming that one command applies everywhere. The important workflow is consistent: load schema, load instance, validate, report failures, and fail the check when the contract is not met. A GitHub Actions YAML troubleshooting workflow can help when the validation command works locally but fails in CI.
What to double-check
- Draft declaration: Confirm that the schema's
$schemavalue matches the validator's supported draft. Do not assume that a tool supports every keyword from every draft. - Required versus present: A property is not required merely because it appears in
properties. Add its name to therequiredarray when it must be present. - Defaults: A
defaultannotation generally describes a suggested value; it does not automatically mean that a validator inserts the value into the payload. Check the library's behavior before expecting mutation. - Nullability: Decide whether a field may be absent, explicitly
null, or both. These are different cases and should be represented intentionally. - Numbers: Check whether values should be integers or can include decimals. Also define minimum and maximum limits when they are part of the contract.
- Strings: Use formats, patterns, and length limits only when the application can enforce and explain them. A format annotation may receive different levels of enforcement across tools.
- Unknown properties: Decide whether forward-compatible clients should ignore extra fields or whether unexpected fields should fail validation.
- Arrays: Define item types and, where relevant, uniqueness, minimum length, or maximum length.
- Errors: Preserve the failing instance path. “Invalid payload” is much less useful than “
/items/2/quantitymust be an integer.”
Common mistakes
Using a JSON formatter as a schema validator. Formatting confirms or exposes syntax problems, but it does not prove that the data follows an API contract.
Generating a schema from one example and publishing it unchanged. Automatic generation can infer types, but it cannot reliably determine business requirements, optionality, or future compatibility from a single document.
Assuming defaults are applied. Validation and data transformation are separate operations. If an application needs missing values inserted, implement and test that behavior explicitly.
Making every property required. Overly strict schemas can reject legitimate partial updates, older clients, or responses where fields are conditionally included.
Testing only the happy path. Add deliberately invalid fixtures. Missing fields, wrong types, null values, and extra properties often reveal more useful contract problems than another valid example.
Ignoring tool differences. A browser validator, editor extension, and runtime library may use different drafts, formats, and options. Reproduce important failures with the same configuration used in the application or CI.
Pasting production payloads into an unknown service. Use redacted fixtures and review the tool's privacy and processing model. For sensitive data, local validation is the safer default.
When to revisit
Revisit a JSON Schema whenever the API contract, validator, or development workflow changes. This includes adding or removing fields, changing a type, introducing pagination, changing error objects, or deciding that a previously optional property is required. Update valid and invalid fixtures at the same time so the tests explain the new behavior.
Also review the setup before a new project cycle, after moving validation into CI, or when developers report inconsistent results between an editor, local command, and deployed application. Confirm the supported JSON Schema draft, validator version, editor integration, command examples, payload-size limits, and privacy controls. These details can change independently of the schema itself.
Use this final checklist before committing a contract:
- Is the schema draft declared and supported by the chosen validator?
- Are required, nullable, optional, and defaulted fields distinguished?
- Have representative valid and invalid payloads been tested?
- Do validation errors identify useful instance paths?
- Are sensitive examples redacted or validated locally?
- Does the same check run consistently for developers and CI?
- Has the schema and its fixtures been reviewed with API consumers?
Keeping this checklist with the schema makes validation a repeatable part of data handling rather than a one-time browser check. When the payload changes, update the contract, fixtures, and tool configuration together.