Need help with your JSON?

Try our JSON Formatter tool to automatically identify and fix syntax errors in your JSON. JSON Formatter tool

JSON Schema Validation Errors and Their Meaning

JSON Schema provides a powerful way to validate the structure and content of JSON documents. When validation fails, various error messages indicate what went wrong. Understanding these error messages is crucial for diagnosing and fixing issues in your JSON data. This article explains common JSON Schema validation errors and their meanings.

Introduction to JSON Schema Validation

JSON Schema is a vocabulary that allows you to validate JSON documents against a set of rules. These rules can specify:

Data types for properties
Required vs. optional properties
Value constraints (minimum, maximum, pattern, etc.)
Object and array structure requirements
Complex logical conditions using combinations of rules

Example JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["name", "email", "age"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    }
  }
}

Common JSON Schema Validation Errors

1. Required Property Missing

This error occurs when a property specified as required in the schema is missing from the JSON document.

Error Message:

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

Explanation:

This error indicates that the "email" property, which is marked as required in the schema, is missing from the validated JSON document.

Fix:

Add the missing property to your JSON document:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

2. Type Mismatch

Type mismatches occur when a property in the JSON document has a different data type than what the schema requires.

Error Message:

{
  "keyword": "type",
  "dataPath": ".age",
  "schemaPath": "#/properties/age/type",
  "params": {
    "type": "integer"
  },
  "message": "should be integer"
}

Explanation:

This error indicates that the "age" property in the JSON document is not an integer as required by the schema. It might be a string, float, or another type.

Fix:

Change the value type to match the schema requirement:

// Incorrect
{
  "age": "30"  // String value
}

// Correct
{
  "age": 30  // Integer value
}

3. Minimum/Maximum Value Constraints

These errors occur when numeric values fall outside the allowed range specified in the schema.

Error Message:

{
  "keyword": "minimum",
  "dataPath": ".age",
  "schemaPath": "#/properties/age/minimum",
  "params": {
    "comparison": ">=",
    "limit": 18,
    "exclusive": false
  },
  "message": "should be >= 18"
}

Explanation:

This error indicates that the value of the "age" property is less than the minimum allowed value of 18.

Fix:

Ensure the value is within the specified range:

// Incorrect
{
  "age": 16  // Below minimum
}

// Correct
{
  "age": 18  // Meets minimum requirement
}

4. String Length Constraints

These errors occur when string values don't meet the length requirements in the schema.

Error Message:

{
  "keyword": "minLength",
  "dataPath": ".name",
  "schemaPath": "#/properties/name/minLength",
  "params": {
    "limit": 2
  },
  "message": "should NOT be shorter than 2 characters"
}

Explanation:

This error indicates that the "name" property contains a string that is shorter than the minimum length of 2 characters.

Fix:

Ensure the string meets the length requirements:

// Incorrect
{
  "name": "J"  // Too short
}

// Correct
{
  "name": "Jo"  // Meets minimum length
}

5. Pattern Matching Errors

Pattern errors occur when a string value doesn't match the regular expression pattern defined in the schema.

Error Message:

{
  "keyword": "pattern",
  "dataPath": ".postal_code",
  "schemaPath": "#/properties/postal_code/pattern",
  "params": {
    "pattern": "^\d{5}(-\d{4})?$"
  },
  "message": "should match pattern "^\\d{5}(-\\d{4})?$""
}

Explanation:

This error indicates that the "postal_code" property doesn't match the US ZIP code pattern (5 digits, optionally followed by a hyphen and 4 more digits).

Fix:

Format the string to match the required pattern:

// Incorrect
{
  "postal_code": "ABC123"  // Not matching pattern
}

// Correct
{
  "postal_code": "12345"  // Matches pattern
}

// Also correct
{
  "postal_code": "12345-6789"  // Matches alternative pattern
}

6. Format Validation Errors

Format errors occur when a string does not conform to the specified format (like email, date, URI).

Error Message:

{
  "keyword": "format",
  "dataPath": ".email",
  "schemaPath": "#/properties/email/format",
  "params": {
    "format": "email"
  },
  "message": "should match format \"email\""
}

Explanation:

This error indicates that the "email" property doesn't conform to the email address format.

Fix:

Ensure the string matches the required format:

// Incorrect
{
  "email": "john.example.com"  // Missing @ symbol
}

// Correct
{
  "email": "john@example.com"  // Valid email format
}

7. Enum Validation Errors

Enum errors occur when a value is not one of the allowed values specified in the schema.

Error Message:

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

Explanation:

This error indicates that the "status" property contains a value that is not in the list of allowed values.

Fix:

Use one of the allowed enum values:

// Incorrect
{
  "status": "cancelled"  // Not in allowed values
}

// Correct
{
  "status": "inactive"  // One of the allowed values
}

8. Array Validation Errors

These errors occur when arrays in the JSON don't meet the requirements specified in the schema.

Error Message:

{
  "keyword": "uniqueItems",
  "dataPath": ".tags",
  "schemaPath": "#/properties/tags/uniqueItems",
  "params": {
    "i": 2,
    "j": 0
  },
  "message": "should NOT have duplicate items (items ## 0 and 2 are identical)"
}

Explanation:

This error indicates that the "tags" array contains duplicate items, which violates the "uniqueItems" constraint.

Fix:

Remove duplicate items to ensure uniqueness:

// Incorrect
{
  "tags": ["javascript", "react", "javascript"]  // Contains duplicates
}

// Correct
{
  "tags": ["javascript", "react", "typescript"]  // All unique
}

Logical Schema Validation Errors

JSON Schema supports logical operators (allOf, anyOf, oneOf, not) that can result in more complex error messages.

1. AllOf Validation Errors

These errors occur when the data fails to satisfy all the schemas in an allOf array.

Error Message:

{
  "keyword": "allOf",
  "dataPath": "",
  "schemaPath": "#/allOf",
  "params": {},
  "message": "should match all schemas in allOf"
}

Explanation:

This error indicates that the JSON document doesn't satisfy all the schemas specified in the allOf array. The validator usually provides more specific errors for each subschema that failed.

Fix:

Ensure the JSON satisfies all the conditions in each subschema of the allOf array.

2. OneOf Validation Errors

These errors occur when the data doesn't satisfy exactly one schema in a oneOf array.

Error Message:

{
  "keyword": "oneOf",
  "dataPath": "",
  "schemaPath": "#/oneOf",
  "params": {
    "passingSchemas": [0, 1]  // Failed because it matched more than one schema
  },
  "message": "should match exactly one schema in oneOf"
}

Explanation:

This error indicates that the JSON document matches more than one schema in the oneOf array, when it should match exactly one.

Fix:

Modify the JSON so it matches exactly one of the schemas in the oneOf array.

Troubleshooting JSON Schema Validation Errors

Examine the error message carefully - Most validators provide detailed information about the location and nature of the error.
Check the dataPath - This tells you exactly which part of your JSON document failed validation.
Review the schema requirements - Compare your data against the specific requirements in the schema at the given schemaPath.
Use a JSON Schema validator with good error reporting - Some validators provide more user-friendly error messages than others.
For complex schemas - Break down validation into smaller parts to isolate the issue.

Important Note:

Error messages can vary between different JSON Schema validator implementations. The examples in this article follow the format used by AJV, one of the most popular JSON Schema validators.

Conclusion

Understanding JSON Schema validation errors is essential for working effectively with schema-validated JSON. The error messages provide valuable clues about what's wrong with your data and how to fix it. By learning to interpret these messages, you can more quickly diagnose and resolve issues in your JSON documents.

As you become more familiar with JSON Schema validation, you'll find that error messages become easier to interpret and fix. This knowledge will help you create more robust applications that properly validate and process JSON data.

Need help with your JSON?

Try our JSON Formatter tool to automatically identify and fix syntax errors in your JSON. JSON Formatter tool