JSON Schema Validation Errors and Their Meaning

A JSON Schema validation error is a map back to the rule your data broke. The fastest way to fix one is to ignore the vague human wording for a moment and read four fields instead: the failing keyword, the JSON location in instancePath, the rule location in schemaPath, and the extra details in params.

That matters because examples online are often outdated. Many older articles show draft-07 schemas and Ajv errors with dataPath. Modern tooling commonly validates newer drafts such as 2020-12, and Ajv v8 reports instancePath instead. The exact text can vary, but the meaning stays the same.

A Typical Error, Decoded

Here is a current-style validation error object you may see from a validator such as Ajv v8:

{
  "keyword": "required",
  "instancePath": "",
  "schemaPath": "#/required",
  "params": {
    "missingProperty": "email"
  },
  "message": "must have required property 'email'"
}

• keyword: the schema rule that failed. Here it is required.
• instancePath: where the failing value lives in your JSON document. An empty string means the root object.
• schemaPath: where the broken rule lives in the schema, usually as a JSON Pointer.
• params: validator-supplied details that make the error actionable.
• message: a readable summary. Useful for humans, but not stable enough to parse in code.

In this example, the empty instancePath tells you the error is on the top-level object, and params.missingProperty tells you exactly which key is missing.

Example Schema

This schema uses the current 2020-12 meta-schema and a few keywords that commonly produce validation errors.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email", "age"],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120
    },
    "status": {
      "enum": ["active", "pending", "inactive"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true,
      "minItems": 1
    }
  }
}

Common JSON Schema Validation Errors

1. Required Property Missing

This happens when an object is missing a property listed under required. With this keyword, the path usually points to the parent object, not the missing child.

{
  "keyword": "required",
  "instancePath": "",
  "schemaPath": "#/required",
  "params": {
    "missingProperty": "email"
  },
  "message": "must have required property 'email'"
}

Meaning: The object being validated is missing the email key.

Fix: Add the property, or remove it from required if it is genuinely optional.

2. Type Mismatch

Type errors are among the most common failures. They mean the data exists, but its JSON type does not match the schema.

{
  "keyword": "type",
  "instancePath": "/age",
  "schemaPath": "#/properties/age/type",
  "params": {
    "type": "integer"
  },
  "message": "must be integer"
}

Meaning: The value at /age is present, but it is not an integer.

Fix: Change the JSON value to the right type. A quoted number like "30" is still a string, not a number.

3. Additional Properties Not Allowed

When a schema sets additionalProperties to false, any unexpected key will fail validation.

{
  "keyword": "additionalProperties",
  "instancePath": "",
  "schemaPath": "#/additionalProperties",
  "params": {
    "additionalProperty": "nickname"
  },
  "message": "must NOT have additional properties"
}

Meaning: Your JSON includes a key the schema does not allow.

Fix: Remove the extra property, add it under properties, or relax the schema if unknown keys are acceptable.

4. Enum or Const Failure

These errors mean a value is structurally valid but not one of the exact values allowed by the schema.

{
  "keyword": "enum",
  "instancePath": "/status",
  "schemaPath": "#/properties/status/enum",
  "params": {
    "allowedValues": ["active", "pending", "inactive"]
  },
  "message": "must be equal to one of the allowed values"
}

Meaning: The value does not exactly match one of the allowed literals.

Fix: Check spelling, case, and whether the API expects a stable internal code instead of a display label.

5. Numeric, Length, and Count Constraints

Keywords such as minimum, maximum, minLength, maxLength,minItems, and maxItems all mean the same general thing: the value is the right type, but outside the allowed boundary.

{
  "keyword": "minimum",
  "instancePath": "/age",
  "schemaPath": "#/properties/age/minimum",
  "params": {
    "comparison": ">=",
    "limit": 18
  },
  "message": "must be >= 18"
}

Meaning: The value exists and has the expected type, but it falls outside the accepted range.

Fix: Compare the failing value directly with the limit in params.

6. Pattern Errors

Pattern failures come from the pattern keyword and mean a string did not match the required regular expression.

{
  "keyword": "pattern",
  "instancePath": "/postalCode",
  "schemaPath": "#/properties/postalCode/pattern",
  "params": {
    "pattern": "^\\d{5}(-\\d{4})?$"
  },
  "message": "must match pattern \"^\\d{5}(-\\d{4})?$\""
}

Meaning: The input is a string, but it does not satisfy the regex rule.

Fix: Test the regex independently and make sure it matches the entire intended value, not just part of it.

7. Format Validation Errors

A format error often looks simple, but it is one of the most misunderstood validation failures. The important caveat is that format behavior depends on the validator.

{
  "keyword": "format",
  "instancePath": "/email",
  "schemaPath": "#/properties/email/format",
  "params": {
    "format": "email"
  },
  "message": "must match format \"email\""
}

Meaning: The string failed a validator's implementation of a known format such as email, uri, or date-time.

Fix: Confirm that format assertions are actually enabled in your validator. If you expected a format error and did not get one, that is often a validator configuration issue rather than a schema issue.

8. Array Errors Such as uniqueItems or minItems

Array keywords tell you whether the list shape is acceptable: how many items it contains, whether duplicates are allowed, and whether each item matches the declared schema.

{
  "keyword": "uniqueItems",
  "instancePath": "/tags",
  "schemaPath": "#/properties/tags/uniqueItems",
  "params": {
    "i": 2,
    "j": 0
  },
  "message": "must NOT have duplicate items"
}

Meaning: The array itself exists, but its contents break one of the array rules.

Fix: Check whether the failure is about count, duplicates, or an invalid item type at a more specific nested path.

9. oneOf, anyOf, and allOf Errors

Combination keywords are where validation errors become noisy. The top-level message is often less useful than the nested branch errors that come with it.

{
  "keyword": "oneOf",
  "instancePath": "",
  "schemaPath": "#/oneOf",
  "params": {
    "passingSchemas": [0, 1]
  },
  "message": "must match exactly one schema in oneOf"
}

Meaning: The data either matched none of the candidate schemas, or matched too many of them.

Fix: Inspect the branch-level errors and make the alternatives more clearly distinct. When possible, use a discriminator field such as type or kind so each branch is easier to identify.

Why Your Errors May Look Different

If your validator output does not match the examples above exactly, that is normal. There are three common reasons:

1. Different draft support: the current published JSON Schema draft is 2020-12, but many code bases still use draft-07 or 2019-09.
2. Different validator output formats: some tools expose their own error objects, while others follow the JSON Schema recommended output shapes.
3. Different validator versions: older Ajv examples use dataPath; newer ones use instancePath.

When you are debugging, treat the human message as a hint and rely on the structural fields first. Those are what survive across validator versions, localization, and UI wrappers.

A Practical Troubleshooting Checklist

1. Start with keyword. It tells you which schema rule to inspect first.
2. Follow instancePath into the JSON document to find the exact failing value.
3. Follow schemaPath into the schema to see the rule in context.
4. Read params for specifics such as missingProperty, allowedValues, or numeric limits.
5. If the error is required, remember the path usually points to the parent object.
6. If the error is oneOf or anyOf, inspect branch errors instead of stopping at the summary line.
7. If format behaves strangely, verify validator configuration before rewriting your schema.

Conclusion

JSON Schema validation errors are much easier to interpret once you stop reading them as prose and start reading them as structured diagnostics. Focus on the keyword, the instance path, the schema path, and the params object. Those four pieces usually tell you exactly what failed and how to fix it.

If you keep seeing examples with older field names or different wording, do not assume your validator is wrong. Compare the error shape, the schema draft, and whether optional features like format assertions are enabled, then debug from the structure rather than the wording.