JSON Schema Validation in API Workflows

Production 500s traced to quantity: "12" — string, not number. TypeScript types on server were wrong; client "worked" until a new mobile build sent strings from a form field. No runtime validator at the boundary.

JSON Schema at the door would have returned 400 Bad Request with a clear path /quantity expected number.

Validation layers

| Layer | When | Catches | | --- | --- | --- | | CI fixtures | PR merge | Doc/sample drift | | Unit tests | Dev | Handler edge cases | | Runtime middleware | Request hit | Bad clients | | Response tests | PR | Breaking API changes | | Gateway (Kong, etc.) | Edge | External traffic |

Defense in depth — not pick one.

Authoring schemas

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

additionalProperties: false catches typos early — debate internally for public APIs (forward compatibility).

Craft fixtures in JSON Formatter, validate with JSON Validator.

JSON Formatting Guide, Common JSON Formatting Errors.

OpenAPI as source

Define components.schemas → generate TypeScript types (openapi-typescript) → validators (ajv).

Drift happens when code changes without spec update — CI must validate samples against spec.

CI workflow example

1. openapi.yaml in repo
2. Example files examples/create-order.json
3. CI step: ajv validate -s schema -d examples/*.json
4. Contract test: supertest response .toMatchSchema()

Pretty-print failures — JSON Pretty Print CI — redact tokens.

Runtime (Node example)

import Ajv from "ajv";
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(orderSchema);

if (!validate(req.body)) {
  return res.status(400).json({ errors: validate.errors });
}

Return RFC 7807 problem+json for clarity.

Versioning schemas

/v1/ schemas frozen; /v2/ additive changes. Don't mutate v1 schema in breaking ways — new schema file.

UUID v4 vs v7 — format: uuid in schema.

JSON Schema vs JSONL

JSON vs JSONL — line-delimited logs need per-line schema validation in stream processors.

Regex in schema

pattern for codes — test in Regex Tester — Regex Email Truth shows format pitfalls.

Performance

Compile schemas once at startup. Large payloads — validate structure before deep business rules.

Troubleshooting

What is JSON Schema used for in APIs? JSON Schema defines expected structure — types, required fields, enums, formats — for JSON documents. Validators check incoming requests and outgoing responses against schemas before business logic or after code changes in CI.

Should I validate API requests at runtime or only in tests? Both. Runtime validation at API boundary protects production from bad clients. CI validation against fixtures catches schema regressions when code changes. Gateway validation optional middle layer.

How does JSON Schema relate to OpenAPI? OpenAPI 3.x embeds JSON Schema (with subset/dialect differences) for request/response models. Single source of truth in OpenAPI can generate schemas, docs, and validators — keep them synchronized.

Limitations

When not to use this approach

Conclusion

Schema at boundary + fixtures in CI — types alone don't survive HTTP.

Return 400 with paths, not 500 mysteries. quantity as string dies at the door, not in accounting.

Partial validation for webhooks

Stripe-style webhooks — validate event envelope schema, defer nested object validation to handler with specific schema per event type. Fail fast on malformed envelope; typed handlers for payload.

Schema versioning in CI

schemas/v1/order.json and schemas/v2/order.json coexist — CI validates examples in examples/v1/ against matching version. Prevent v2 example validating against v1 schema falsely passing.

Error response quality

Return JSON Pointer in validation error: {"path": "/quantity", "message": "expected number"} — mobile clients highlight field. Generic "validation failed" increases support tickets.