Common JSON Schema Validator Errors and How to Fix Them
Common JSON Schema Validation Errors
JSON Schema validation errors can be cryptic. Here's how to diagnose and fix the most common ones.
1. "should match exactly one schema in oneOf"
Cause: Your data matches either too many or too few schemas in a oneOf constraint.
Fix: Check each sub-schema in your oneOf array. Add stricter properties to differentiate them. Use enum or const constraints to create mutually exclusive conditions.
2. "should NOT have additional properties"
Cause: The schema uses additionalProperties: false but your data contains properties not listed in the schema's properties object.
Fix: Either add the unexpected property to your schema, set additionalProperties: true to allow arbitrary properties, or use unevaluatedProperties for more nuanced control.
3. "should be string" or "should be number"
Cause: A value has the wrong data type. Common cases include numbers as strings, or null values where an object is expected.
Fix: Check your data source for type coercion issues. Use type: ["string", "null"] if null is allowed. Frontend forms often send numeric values as strings — fix with parseInt() or Number().
4. "should match pattern"
Cause: A string value doesn't match the regex pattern defined in the schema.
Fix: Test your regex thoroughly. Use tools like regex101.com. Common pitfalls: forgetting anchors (^ and $), not escaping special characters, or mismatched character classes.
5. "should NOT have null value" or null interjection
Cause: A field expected to be a specific type received null instead. This often happens with API responses that return null for optional fields.
Fix: Use default keyword to provide fallback values. Set type: ["string", "null"] to explicitly allow null. Validate at the data source to prevent null from entering your pipeline.
6. "should be integer" vs "should be number"
Cause: JSON Schema distinguishes between integer (whole numbers) and number (any numeric value). Using integer when your data has decimals causes this error.
Fix: Use type: "number" for floating-point values, or validate with multipleOf: 1 if you want both integer-type checking and decimal rejection.
7. "should be equal to const"
Cause: The data value doesn't match the exact const value defined in the schema. This is an exact-equality check, including type.
Fix: "const": true requires the boolean true, not the string "true". Check for type mismatches first, then value mismatches.
8. Schema not loading (fetch errors)
Cause: The schema file URL is wrong, CORS is blocking it, or the file doesn't exist at the specified path.
Fix: Verify the schema URL with curl or in your browser. For local development, use file:// or relative paths. For cross-origin, ensure proper CORS headers are set.
9. "should NOT have format" errors
Cause: The format keyword requires specific format validation (e.g., "format": "email"). Many validators don't validate formats by default.
Fix: In AJV, add formats via ajv.addFormat() or use ajv-formats plugin. In other validators, check if format validation is enabled or needs a plugin.
10. Recursive $ref causing stack overflow
Cause: Circular references in your schema (e.g., a schema that references itself infinitely through nested defs).
Fix: Use \(recursiveAnchor and \)recursiveRef for Draft 2019-09+. For Draft 07, restructure to avoid circular patterns or use maxDepth to limit recursion.
Summary
Most JSON Schema validation errors fall into predictable categories: type mismatches, structure violations, format issues, and reference problems. Understanding these patterns lets you diagnose and fix errors quickly. When in doubt, use xingdian.net's validator to test your schema step by step.
Check out xingdian.net's JSON Schema Validator for free online processing.
Originally published on xingdian.net