JSON Schema Validation Errors: Examples and Fixes

JSON syntax errors and schema validation errors are different

Parsing answers whether a document is valid JSON. Schema validation answers whether a parsed value meets a separate contract, such as an API request body or configuration format. A valid JSON string can fail a schema requiring an integer, and a correctly formatted object can be missing mandatory keys.

Check the raw data with the JSON Validator before interpreting schema errors. Once both documents parse, compare the instance against the schema using the JSON Schema Validator; changing indentation or reformatting JSON will not repair a contract mismatch.

Fix required fields and property type mismatches

The required keyword names properties that must exist on an object; a property with a null value is still present, but null may fail a type check. The properties keyword applies subschemas to named members. An integer schema accepts 42, not the string "42". For optional fields, remove the key from required instead of inserting an artificial default.

When a producer serializes numbers as strings, correct the producer or deliberately extend the contract to allow both representations. Do not weaken a production API schema just to conceal a broken payload.

{
  "type": "object",
  "required": ["name", "age"],
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  }
}

{
  "age": "42"
}

{
  "name": "Ada",
  "age": 42
}

Understand additionalProperties and extra object keys

With additionalProperties set to false, an object rejects members not declared by its applicable property definitions. If your payload contains an unexpected key, check for a typo first. Otherwise either declare the legitimate field in properties or remove it from the payload.

Do not automatically disable additionalProperties on every object: flexible API metadata and extensible configuration often need additional keys. Make the rule reflect the actual contract rather than choosing the strictest setting by default.

{
  "type": "object",
  "properties": { "id": { "type": "integer" } },
  "required": ["id"],
  "additionalProperties": false
}

{ "id": 12, "debug": true }

Locate errors inside arrays and nested objects

JSON Pointer expresses the location of a failing value using slash-separated segments. /items/2/sku identifies the sku member of the third item, because array indexes start at zero. Within pointer segments, ~1 represents a literal slash and ~0 represents a literal tilde.

If items requires an object and one element is a string, fix that element rather than editing every array member. For tuples, Draft 2020-12 uses prefixItems for position-specific schemas; do not copy an older Draft 7 items tuple schema without checking the target dialect.

{
  "items": [
    { "sku": "A-1" },
    { "sku": "B-2" },
    { "sku": 1003 }
  ]
}

/items/2/sku — Expected string but received number.

Check dialects, references, and unsupported keywords

JSON Schema defines multiple drafts with different keyword semantics. A declared $schema such as https://json-schema.org/draft/2020-12/schema identifies the intended dialect; Draft 7 differs in its array tuple rules and local definition conventions.

VetaTool's browser-local validator supports documented subsets of Draft 7 and Draft 2020-12, not every feature in either specification. It resolves supported local JSON Pointer references without fetching remote schemas, and explicitly rejects unsupported features rather than silently reporting success. For full-specification conformance, use a validator certified for the required draft and vocabulary.

• Check whether a referenced local definition is actually present.
• Check the draft before choosing definitions vs $defs or items vs prefixItems.
• Do not assume remote $ref, patternProperties, conditional schemas, or dynamic references work in the local tool.
• Retest both a valid sample and a deliberately invalid sample to verify your rules catch the intended failure.

A repeatable workflow for API and configuration payloads

Start with representative valid and invalid samples. If no schema exists, the JSON Schema Generator can infer a starting contract from multiple samples, but inference is not a substitute for deciding required and optional fields with the API owner.

Paste the reviewed schema and payload into the JSON Schema Validator, inspect each pointer and failing keyword, and make the smallest intentional correction. Rerun validation, then preserve representative fixtures in your application tests so the same contract regression cannot silently return.

• Validate JSON syntax before testing a schema.
• Generate an initial schema only when the contract is not yet documented.
• Choose and record the expected JSON Schema draft.
• Repair schema or data based on the actual contract, then rerun positive and negative cases.