How to validate JSON

There are three separate questions behind "is my JSON valid": does it parse, does it mean what you intended, and does it match the shape a consumer expects — and only the first is answered by a syntax check.

Level 1: does it parse?

The cheapest check, and the only one most tools perform. Either the grammar is satisfied or it is not.

# jq: silent on success, prints the position of the error on failure
jq empty data.json

# Python, no dependencies
python -m json.tool data.json > /dev/null

try {
  JSON.parse(text);
} catch (error) {
  // The message includes the character offset in most engines
  console.error(error.message);
}

The five errors that account for most failures

Level 2: does it mean what you think?

A document can parse perfectly and still be wrong. The clearest example is a duplicate key.

{
  "timeout": 30,
  "retries": 3,
  "timeout": 300
}
// Valid JSON. Almost every parser gives you 300.
// The 30 is gone, silently, with no error anywhere.

The specification leaves this undefined rather than forbidding it, so no syntax check will flag it. Detecting it properly requires tracking object scopes — the same key appearing in two sibling objects is legal and extremely common, so a tool that searches the text for repeated strings will produce false positives on nearly every real document.

{
  "users": [
    { "name": "Ada" },
    { "name": "Grace" }
  ]
}

Level 3: does it match a schema?

JSON Schema describes the shape a document should have: which fields exist, what types they hold, which are required, what values are allowed. It is the only one of the three levels that can catch a field that is a string when it should be a number.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "port"],
  "properties": {
    "name":  { "type": "string", "minLength": 1 },
    "port":  { "type": "integer", "minimum": 1, "maximum": 65535 },
    "debug": { "type": "boolean" },
    "tags":  { "type": "array", "items": { "type": "string" } }
  },
  "additionalProperties": false
}

{
  "name": "checkout",
  "port": "8080",
  "colour": "blue"
}

// port is a string, not an integer
// colour is not in the schema, and additionalProperties is false
// debug is absent, which is fine — it was not required

Which draft you are using matters

JSON Schema has several revisions — draft-04 through 2020-12 — and they are not interchangeable. A validator built for draft-07 given a 2020-12 schema typically fails with "no schema with key or ref", which reads like a broken reference rather than a version mismatch. Declare the draft with $schema, and use a validator that reads it.

npx ajv-cli validate -s schema.json -d data.json

# For a 2020-12 schema, the draft has to be selected explicitly:
npx ajv-cli --spec=draft2020 validate -s schema.json -d data.json

Generating a schema from data you already have

Writing a schema by hand for an existing payload is tedious. Inferring one from a sample gets you most of the way, and then you correct it — inference can see that a field is a string, but not that it must be a valid email, and it will mark every field it saw as required whether or not it is.

Validating in a build or CI

- name: Validate configuration
  run: |
    for file in config/*.json; do
      jq empty "$file" || exit 1
    done
    npx ajv-cli validate -s schema.json -d "config/*.json"

Validating configuration in CI is one of the highest-return checks available: it costs seconds and catches the class of failure that otherwise surfaces at deploy time, in production, on a Friday.

Validate JSON in your browserSyntax, duplicate keys and JSON Schema. Nothing uploaded.