JSON Schema: How to Validate API Responses Before They Break Your App

If you've ever shipped a bug because an API returned null where you expected a string, you've already experienced the problem JSON Schema solves.

JSON Schema is a vocabulary that lets you describe the structure of your JSON data and validate it automatically. It's been around since 2009 and is now a draft standard under the IETF. If you work with APIs, configs, or any structured JSON, it's worth knowing.

What JSON Schema actually does

A JSON Schema is itself a JSON document that describes what valid JSON looks like. Here's a minimal example:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  }
}

This schema says: the JSON must be an object with id (integer) and email (string, email format) as required fields. age is optional but, if present, must be a non-negative integer under 150.

Run any JSON against this schema and you get a pass/fail result with specific error messages.

The core keywords you need to know

Type keywords: "type": "string", "type": "integer", "type": "number", "type": "boolean", "type": "array", "type": "object", "type": "null". You can allow multiple types with an array: "type": ["string", "null"].

String constraints: minLength, maxLength, pattern (regex). For example: "pattern": "^[a-z]{2,3}$" would match a 2–3 character lowercase language code.

Number constraints: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.

Array constraints: items (schema for each element), minItems, maxItems, uniqueItems. With uniqueItems: true, duplicate entries fail validation.

Object constraints: properties (per-key schemas), required (list of required keys), additionalProperties (set to false to ban keys not listed in properties).

Combining schemas: allOf, anyOf, oneOf, not. These let you compose complex validation rules from simpler ones.

A real-world example

Say you're calling a payment API that returns transaction objects. You want to catch bad responses before they reach your business logic:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["transaction_id", "amount", "currency", "status"],
  "properties": {
    "transaction_id": { "type": "string", "minLength": 1 },
    "amount": { "type": "number", "exclusiveMinimum": 0 },
    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
    "status": { "type": "string", "enum": ["pending", "completed", "failed", "refunded"] },
    "metadata": { "type": "object" }
  },
  "additionalProperties": false
}

This rejects: zero or negative amounts, currencies that aren't 3-letter ISO codes, statuses outside the defined enum, and any unexpected extra fields.

Where JSON Schema is used

API contract testing — validate responses from external APIs before processing
Configuration files — VS Code uses JSON Schema to provide autocomplete and inline validation for settings.json, launch.json, and many extension configs
Form validation — libraries like Ajv run schema validation client-side
CI pipeline checks — validate generated artifacts before deploying
OpenAPI specs — OpenAPI 3.x uses JSON Schema for request/response body definitions

Draft versions and compatibility

The most widely supported version is draft-07. Draft-04 is still common in older codebases. Newer drafts (2019-09, 2020-12) add features like $defs, unevaluatedProperties, and prefixItems for tuple validation, but library support is patchy.

If you're starting fresh, use draft-07 — you get broad tool and library support with minimal compatibility headaches.

Validating quickly without writing code

If you want to test a schema against some JSON right now without setting up a project, you can use a browser-based validator. I built one at SnappyTools JSON Formatter for formatting and validating JSON structure — paste your JSON, see errors highlighted instantly, all client-side with no data sent anywhere.

For schema-specific validation (pairing a schema with an instance and seeing which keywords fail), tools like jsonschema.dev and jsonschemavalidator.net are useful references.

The quick takeaway

JSON Schema is the most practical way to add a validation layer between your app and untrusted JSON data. You don't need a library for simple cases — just knowing the keywords lets you write schemas by hand and reason about what JSON your code will accept.

Start with type, required, and properties. Add minimum/maximum for numbers, pattern for strings, and enum for fixed value sets. That covers 80% of real-world validation needs.

推荐订阅源

DEV Community