Read JSON Schema errors without chasing every message.

A schema error tells you where a value breaks a contract, but the first message is not always the underlying cause. Learn how to locate the failing data, interpret common validation keywords, separate syntax problems from schema mismatches, and make corrections in an order that reduces noise.

Separate syntax from the contract

A JSON parser answers a grammatical question: can these characters represent a JSON value? A schema validator answers a contractual question: does that value satisfy a particular set of rules? A document can pass parsing while failing its schema because an age is negative, a required identifier is absent, or an object contains an unexpected property. Fix parser errors before interpreting schema failures, because validation needs a successfully parsed value.

This distinction determines where you make the correction. Invalid JSON usually requires changing punctuation, quoting, or literal syntax in the document. A schema mismatch requires checking both the document and the contract: perhaps the payload is wrong, or perhaps the schema describes an older API version. Use the JSON Schema validator at /json-schema-validator to inspect failures against the schema you actually intend to enforce.

Read the path, keyword, and message

An Ajv error typically combines an instancePath identifying the data location, a keyword identifying the failed rule, and a human-readable message. The raw error also carries details such as schemaPath and params. A display can combine the instance path and message into /age: must be >= 0. Here, age is the failing property, minimum is the relevant keyword, and zero is the permitted lower boundary.

Read instance paths as JSON Pointers rather than JavaScript expressions. The path /users/2/age identifies the age property in the third array element because indexes begin at zero. Pointer segments escape a slash as ~1 and a tilde as ~0, so a key containing a slash does not introduce another level. An empty instance path identifies the document root, not an unknown location or a missing error detail.

Resolve presence and shape failures

A required failure usually points to the containing object because the missing property has no value to point at. Inspect the message or missingProperty parameter to learn which property must be supplied. A type failure instead concerns an existing value: the string "42" is not the number 42. Do not convert it automatically until you establish whether the contract expects a numeric quantity or an identifier whose leading zeros matter.

An enum failure means the value does not equal any permitted choice; capitalization and JSON types matter. An additionalProperties failure means an object includes a key the schema does not allow. Check spelling and nesting before deleting it, since a misplaced field can be legitimate elsewhere. Also remember that listing properties does not make them mandatory: presence is controlled separately through required, so optional fields can still have strict type rules.

Check boundaries and string constraints

For minimum and maximum failures, compare the actual numeric value with the stated inclusive boundary; exclusiveMinimum and exclusiveMaximum exclude the boundary itself. A pattern failure concerns a string and the schema's regular expression. JSON Schema patterns are not implicitly anchored, so a rule intended to constrain the entire string generally needs explicit start and end anchors. Check the expression before assuming the input alone is at fault.

A format failure concerns a semantic convention such as an email address or date representation, but format enforcement depends on validator configuration and supported formats. Confirm that the chosen format is recognized before relying on it as a guarantee. A valid date-shaped string also does not prove that an appointment exists or a mailbox can receive mail; those checks belong to application logic beyond structural validation.

Find the cause behind multiple errors

With anyOf, at least one candidate schema must match; with oneOf, exactly one must match. A single object with a wrongly typed discriminator can therefore fail several candidate branches. Validators may report those branch failures plus a final combination error, producing a dozen messages from one underlying mistake. Conversely, oneOf can fail because two branches match, even when no individual field looks obviously invalid.

Start with the error closest to the intended branch: a missing discriminator, an incorrect type, or a required property often explains the rest. Correct that cause and validate again before working through every message. If oneOf reports overlapping matches, inspect how the branches differ and whether their discriminator constraints are genuinely exclusive. Do not add arbitrary fields merely to silence unrelated branches that the payload was never meant to satisfy.

Design schemas for readable failures

Write schemas so a reader can understand the contract without reverse engineering every failure. Give important schemas meaningful titles and describe units, accepted representations, and business constraints in descriptions. These annotations document intent but do not necessarily appear in Ajv's default error messages. Keep required lists explicit at the object level they govern, and avoid making a nested object mandatory accidentally when only its present contents need validation.

Prefer direct constraints over unnecessarily deep combinations, and test the schema with representative invalid examples as well as valid data. Check the errors for a missing field, an unexpected key, a boundary value, and the wrong type. Record the schema version alongside the payload when debugging integrations. After correcting a failure, rerun validation against that same version so a changing contract does not hide an unresolved problem.

Related tools

Frequently asked questions

Can valid JSON fail schema validation?

Yes. Parsing confirms that the text follows JSON syntax, while schema validation checks the resulting value against a contract. A negative age or missing identifier can fail that contract even when every quote, comma, and bracket is correct.

Why does a required error point to the parent object?

The missing property has no existing value for the validator to identify with an instance path. Ajv therefore reports the containing object and supplies the missing property name in the error details. Read both pieces before choosing where to edit.

Should I fix every oneOf error separately?

First identify the intended branch and check its discriminator, required properties, and types. Several branch failures may come from one incorrect field. Correct that cause and validate again; if multiple branches match, inspect the schema for overlapping conditions instead.