JSON Schema Guide: Contracts That Keep APIs Honest

Why schemas matter

Syntax validation proves a document is JSON. Schema validation proves it matches an agreed shape: required properties, value types, enums, ranges, and nested structures. That contract protects producers and consumers from silent drift—“we renamed userId to id last Tuesday” becoming a production incident.

JSON Schema is a vocabulary for describing JSON documents. Draft versions exist; pick one and stick to it across your stack.

A minimal schema

Document:

{
  "id": "usr_1",
  "email": "dev@example.com",
  "age": 30
}

Schema sketch:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "additionalProperties": false
}

This rejects missing emails, non-integer ages, and surprise properties when additionalProperties is false.

Core keywords you will use weekly

• type — object, array, string, number, integer, boolean, null
• properties / items — describe objects and arrays
• required — list mandatory keys
• enum — allow a fixed set of values
• oneOf / anyOf / allOf — compose alternatives
• $ref — reuse definitions

Start simple. Overusing oneOf early creates schemas nobody wants to maintain.

Where to validate

• Ingress — API gateways or request middleware
• Egress — ensure responses match published contracts
• CI — fixtures and example payloads
• Editors — autocomplete and inline errors for config files

Generate types from schemas (or vice versa) to keep TypeScript/Java/Go models aligned. Drift between types and schemas is a classic source of false confidence.

Authoring tips

Write schemas beside example documents. Validate the examples in CI so docs never lie. Prefer explicit required arrays over assuming clients “just know.” Document semantic rules that schemas cannot express (cross-field business logic) in plain language next to the schema.

When debugging a failing validation, pretty-print the instance and read the error path carefully—most libraries point to the exact property that failed. JSON Editor helps you inspect instances and iterate on structure while you draft schemas.

Schema evolution

Additive changes (new optional properties) are usually safe. Removing fields, tightening types, or renaming keys are breaking changes—version your API or your schema identifier. Publish changelogs. Consumer-driven contract tests catch surprises before customers do.

Common mistakes

• Using number when you need integer
• Forgetting arrays can be empty unless minItems says otherwise
• Allowing null implicitly when your language types forbid it
• Copying giant schemas without understanding additionalProperties

Getting started this week

1. Choose one critical request body.
2. Write a schema that matches today’s real examples.
3. Validate those examples in CI.
4. Enforce the schema on the server.
5. Expand coverage to responses.

JSON Schema is not bureaucracy when kept proportional to risk. A focused contract on your most important payloads pays for itself the first time it blocks a bad deploy.