API Schema Validation

Why it matters

Clients are built against the documented structure. A field that changes type, disappears, turns null or is renamed can crash a mobile app or silently corrupt a report while the status is still 200 OK. Such defects are easy to miss by eye and often hit many endpoints at once, for example after a change in how the server serialises its data, that is, turns its objects into JSON.

For the tester, a schema is a partial test oracle — a source of expected results — that comes with the API description. One check covers dozens of fields, catches undocumented fields that may expose internal data, and makes every regression run a structural check. Reviewing a schema also forces the right questions early: optional or nullable, which values, may the API add fields?

Reading a JSON Schema: the keywords that do most of the work

A JSON Schema is itself a JSON document. Each keyword is a rule that a validator applies to the matching part of the response. $schema names the draft the schema follows — the current one is 2020-12 — because validators behave slightly differently between drafts.

The schema below describes the body of GET /orders/{orderId}, built from the keywords most schemas use:

• type: object, array, string, number, integer, boolean or null. A list such as ["string", "null"] allows either.
• required: the fields that must be present; a field listed only in properties is optional. It checks presence, not value: "couponCode": null is present.
• properties: the rule for each named field, applied when the field is there. items does the same for every element of an array.
• enum, pattern, minimum, maxLength and similar: allowed values, text patterns and limits. enum is an exact, case-sensitive match. pattern is a regular expression: ^ORD-[0-9]+$ means "starts with ORD-, then one or more digits, then ends". Without ^ and $ it may match anywhere in the text, so x-ORD-1-y would pass.
• format: a named format such as date-time or email. Validators may treat it as an annotation only, the default in draft 2020-12, so check that yours really rejects a bad value.
• additionalProperties: whether fields not listed in properties may appear. Without it, any extra field is accepted; false rejects them.

{
  Part 1:1"$schema": "https://json-schema.org/draft/2020-12/schema",
  Part 2:2"type": "object",
  Part 3:3"required": ["id", "status", "total", "createdAt", "items"],
  Part 4:4"properties": {
    "id": { "type": "string", Part 5:5"pattern": "^ORD-[0-9]+$" },
    "status": { Part 6:6"enum": ["pending", "paid", "shipped", "cancelled"] },
    "total": { "type": "number", "minimum": 0 },
    "createdAt": { "type": "string", Part 7:7"format": "date-time" },
    "couponCode": { Part 8:8"type": ["string", "null"] },
    "items": {
      "type": "array",
      Part 9:9"minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "qty", "price"],
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer", "minimum": 1 },
          "price": { "type": "number", "minimum": 0 }
        }
      }
    }
  },
  Part 10:10"additionalProperties": false
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "status", "total", "createdAt", "items"],
  "properties": {
    "id": { "type": "string", "pattern": "^ORD-[0-9]+$" },
    "status": { "enum": ["pending", "paid", "shipped", "cancelled"] },
    "total": { "type": "number", "minimum": 0 },
    "createdAt": { "type": "string", "format": "date-time" },
    "couponCode": { "type": ["string", "null"] },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "qty", "price"],
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer", "minimum": 1 },
          "price": { "type": "number", "minimum": 0 }
        }
      }
    }
  },
  "additionalProperties": false
}

Try it: JSON Schema Validator

Where the schema lives: OpenAPI

An OpenAPI document, written in YAML or JSON, describes a whole HTTP API: paths, methods, parameters, request bodies and, for every status code, the response body per media type. Bodies are described with schemas, often defined once under components/schemas and reused with $ref. A validator picks the schema by path, method, status code and media type, so a 404 is checked against the error schema, not the order schema.

Versions matter. OpenAPI 3.1 and 3.2 use JSON Schema 2020-12, plus a few OpenAPI-only keywords. OpenAPI 3.0 uses an extended subset of an older draft: type takes a single value, and a nullable field is written nullable: true instead of a type list. Check the openapi line at the top before you trust a validator's results.

openapi: 3.1.0
info: { title: Orders API, version: 1.0.0 }
paths:
  /orders/{orderId}:
    get:
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: No order with this id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Order:
      type: object
      required: [id, status, total, createdAt, items]
      additionalProperties: false
      properties:
        id: { type: string, pattern: '^ORD-[0-9]+$' }
        status: { enum: [pending, paid, shipped, cancelled] }
        couponCode: { type: [string, 'null'] }
        # ...the other properties, exactly as in the JSON Schema above
    Error:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }

Try it: OpenAPI Viewer Try it: OpenAPI Validator

Worked example: an order that returns 200 OK

A tester calls GET /orders/ORD-1042 and receives 200 OK with the body shown at the end of this section. The status check passes and nothing looks broken at a glance.

Validated against the order schema, the body gives five violations, each a location and the keyword that rejected it, and one pass worth noticing:

• $.status, enum: "Shipped" is not allowed. The documented value is shipped, and a client that compares strings exactly will not recognise it.
• $.total, type: a string where a number is required. A client that adds up totals may join the text or fail.
• $.createdAt, format: not an RFC 3339 date-time — no T separator, no seconds, no offset. Reported only if the validator asserts formats.
• $.items[0], required: the line item has no price.
• $.internalNote, additionalProperties: a field the contract does not allow, here internal data. The OWASP API Security Top 10 (2023) lists exposing such properties under API3, Broken Object Property Level Authorization.
• couponCode is null and passes: it is optional and its type allows null.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "ORD-1042",
  "status": "Shipped",
  "total": "149.50",
  "createdAt": "2026-09-14 10:32",
  "couponCode": null,
  "items": [
    { "sku": "BK-201", "qty": 2 }
  ],
  "internalNote": "VIP customer, call before delivery"
}

Try it: API Schema Validator

What schema validation cannot tell you

A schema describes the shape of valid data, not whether the data is right. Fix every violation above and the response can still be wrong: with "total": 159.50 and one line of two items at 74.75, the schema passes although the items add up to 149.50. A passing check means only that the response is structurally valid against that version of the document.

These need other checks:

• Values and calculations: totals, counts, and whether id is the order you asked for. JSON Schema cannot compare two values or calculate.
• Business rules and state: whether shipped is a valid next status for this order. if/then can express simple conditions, but not the order's history.
• Authorisation: whether this caller may see this order at all.
• Status codes, headers and timing: a body validator does not see them; assert them separately.
• Empty arrays: an empty items list passes any items rule, so a list endpoint returning [] never exercises the item schema. Use minItems where the contract guarantees content, and test data that produces non-empty lists.
• The schema itself: if the document is wrong or out of date, the validator agrees with it. A schema generated from one sample usually marks every field it saw as required and copies the sample's defects; review it against the requirements first.

Try it: JSON Schema Generator

Frequently asked questions

References

• JSON Schema SpecificationJSON SchemaThe vocabulary for describing and validating the shape of JSON documents (types, required properties, formats).
• OpenAPI SpecificationOpenAPI InitiativeThe standard for describing REST APIs: paths, operations, parameters, schemas, responses and security schemes.
• ISTQB GlossaryISTQBThe standard definitions of testing terms — test case, regression testing, severity, priority, boundary value analysis and the rest.
• OWASP API Security Top 10 (2023)OWASP Foundation · 2023The ten most common API weaknesses: broken object-level authorization, broken authentication, unrestricted resource consumption and more.