JSON Schema Validation: Syntax Errors vs Schema Errors

“Invalid JSON” gets used to describe two completely different problems. One is a document that isn't valid JSON at all — a parser can't even build a data structure from it. The other is a document that parses perfectly fine but doesn't match the shape your application expects. Conflating them leads to confusing error messages and debugging time spent looking in the wrong place.

Syntax errors: the document isn't JSON

A syntax error means the text violates the JSON grammar itself — a missing closing brace, a trailing comma after the last item in an array (valid in JavaScript object literals, invalid in strict JSON), an unquoted key, or a stray character. A parser can't recover from this; it fails at a specific character position and can't tell you anything about what the data was supposed to mean, only where the grammar broke down. This is a purely mechanical, text-level problem — fixable by looking at the exact line and column the parser reports.

Schema errors: the document is JSON, but the wrong shape

A schema error means parsing succeeded — you have a valid JavaScript object or array — but it doesn't conform to the rules your application requires: a required field is missing, a value is a string where a number was expected, an enum field contains a value outside its allowed set, or a nested object is missing a required property. JSON Schema (the specification, not to be confused with JSON itself) is the standard way to declare these rules formally, so they can be checked automatically instead of scattered through ad-hoc validation code.

Why the distinction matters for tooling

Good tooling should report these separately, because they point a developer at different places to look. A syntax error means “fix the text formatting” — a schema error means “fix the data or fix the schema.” Reporting both as a generic “JSON is invalid” forces the developer to manually figure out which category they're dealing with before they can even start debugging. This is also why parsing and schema validation are almost always separate steps in a pipeline — you can't validate structure until you've successfully parsed the syntax, so catching syntax problems first and failing fast avoids confusing downstream validation errors on data that was never usable in the first place.

The JSON Formatter on this site parses and pretty-prints JSON entirely in your browser, surfacing syntax errors with their exact position so you can fix malformed input before worrying about whether its shape is correct.

← Back to KeyForge