JSON Schema Validation: A Practical Guide

Syntax validation tells you a JSON file is well-formed. JSON Schema goes further: it tells you whether the data is correct — the right fields, the right types, within the right ranges.

Syntax vs structure

Two different questions:

• Is this valid JSON? — a parser answers this (the validator does it instantly).
• Does this JSON have the fields my app expects? — only a schema answers this.

A file can be perfectly valid JSON and still be wrong for your application. JSON Schema closes that gap.

A minimal schema

Suppose your config must have a string name and an integer port:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "port": { "type": "integer", "minimum": 1, "maximum": 65535 }
  },
  "required": ["name", "port"]
}

This rejects a missing port, a port of "8080" (string, not integer), or a port of 70000 (out of range).

Common keywords

• type — string, number, integer, boolean, object, array, null.
• required — property names that must be present.
• properties — schema for each named property.
• minimum / maximum — numeric bounds.
• minLength / maxLength — string length bounds.
• enum — restrict to a fixed set of values.
• items — schema applied to every array element.

Nested objects

Schemas compose. To validate a nested database object:

{
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "properties": {
        "host": { "type": "string" },
        "port": { "type": "integer" }
      },
      "required": ["host"]
    }
  }
}

Where schemas pay off

• APIs — validate request bodies before processing.
• Config files — fail fast at startup with a clear message.
• Editor tooling — VS Code uses JSON Schema for autocomplete and inline errors in package.json and tsconfig.json.

Start simple

You don't need every keyword on day one. Begin with type, properties, and required — that catches the majority of real bugs. Before schema validation, make sure the file is syntactically valid: paste it into the validator, fix any errors, then layer schema checks on top.