JSON Schema for API Documentation and OpenAPI

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

OpenAPI is the industry standard for describing REST APIs, and JSON Schema is its schema language. Since OpenAPI 3.1, the two are fully unified — every JSON Schema keyword works inside an OpenAPI spec. This guide covers how to write schemas in components/schemas, reuse them with $ref, handle nullable fields, generate TypeScript types, and host interactive docs.

OpenAPI 3.1 and JSON Schema

OpenAPI 3.0 included a subset of JSON Schema Draft-04 with proprietary extensions like nullable and a modified exclusiveMinimum. OpenAPI 3.1 dropped those extensions and adopted JSON Schema Draft 2020-12 wholesale. This means any valid JSON Schema is a valid OpenAPI 3.1 schema object.

# openapi.yaml
openapi: "3.1.0"
info:
  title: User API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email

The components/schemas block is where all reusable schemas live. The path item references the User schema with $ref rather than inlining the definition, keeping the spec DRY and the path items readable.

Defining Schemas in components/schemas

components/schemas is a flat map of schema name to schema object. Names are PascalCase by convention. Each schema is a full JSON Schema — you can use $defs, allOf, oneOf, if/then, and every other keyword.

components:
  schemas:
    # Request schema — no server-set fields
    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        name:
          type: string
          minLength: 1
          maxLength: 100
        plan:
          type: string
          enum: [free, pro, enterprise]
          default: free
      required:
        - email
        - name
      additionalProperties: false

    # Response schema — includes server-set fields
    User:
      type: object
      properties:
        id:
          type: string
          pattern: "^usr_[0-9a-zA-Z]{16}$"
        email:
          type: string
          format: email
        name:
          type: string
        plan:
          type: string
          enum: [free, pro, enterprise]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name
        - plan
        - createdAt
        - updatedAt

    # Error envelope — reused across all error responses
    ApiError:
      type: object
      properties:
        code:
          type: string
          examples:
            - validation_error
            - not_found
            - unauthorized
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
              - field
              - message
      required:
        - code
        - message

Separating request and response schemas is important. Request schemas typically omit id, createdAt, and other server-generated fields, and may add additionalProperties: false for strict input validation. Response schemas include all fields the API returns.

Request Bodies and Response Schemas

Every path operation can have a requestBody (for POST, PUT, PATCH) and one or more responses. Each uses the same JSON Schema under the content media type key.

paths:
  /users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
            # Example shown in Swagger UI / Redoc
            example:
              email: "alice@example.com"
              name: "Alice"
              plan: "pro"
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "409":
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

  /users/{id}:
    patch:
      summary: Partially update a user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: Updated user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

Define a distinct UpdateUserRequest schema for PATCH endpoints. PATCH bodies make all fields optional and require at least one to be present using minProperties: 1.

components:
  schemas:
    UpdateUserRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        plan:
          type: string
          enum: [free, pro, enterprise]
      minProperties: 1
      additionalProperties: false

Schema Reuse with $ref

$ref can point to schemas within the same file (using a JSON Pointer fragment) or to external files. For large APIs, split schemas into separate files and use a bundler.

# Internal $ref — points to the root document
$ref: "#/components/schemas/User"

# External $ref — relative file path
$ref: "./schemas/user.yaml"

# External $ref with JSON Pointer into the file
$ref: "./schemas/common.yaml#/components/schemas/Address"

# Cross-file composition with allOf
components:
  schemas:
    AdminUser:
      allOf:
        - $ref: "#/components/schemas/User"
        - type: object
          properties:
            adminLevel:
              type: integer
              minimum: 1
              maximum: 5
            permissions:
              type: array
              items:
                type: string
          required:
            - adminLevel

In OpenAPI 3.1, $ref can have sibling keywords such as description and summary. This is a change from 3.0 where siblings were silently ignored. Use it to provide context-specific descriptions for referenced schemas without duplicating the schema itself.

# OpenAPI 3.1 — $ref with sibling description
responses:
  "200":
    description: The authenticated user
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/User"
          description: "The currently authenticated user object"
          # In 3.1 this description overrides the referenced schema's description

Nullable and Optional Fields in OpenAPI

Nullability is a common point of confusion when migrating from OpenAPI 3.0 to 3.1. The proprietary nullable: true keyword is replaced by the standard JSON Schema type array syntax.

components:
  schemas:
    UserProfile:
      type: object
      properties:
        id:
          type: string

        # Optional field (not in "required") — can be omitted from the object
        bio:
          type: string

        # Nullable field (must be present but can be null)
        # OpenAPI 3.0 style (avoid in 3.1 specs):
        # avatarUrl:
        #   type: string
        #   nullable: true
        #
        # OpenAPI 3.1 / JSON Schema 2020-12 style:
        avatarUrl:
          type: ["string", "null"]
          format: uri

        # Optional AND nullable (can be omitted or present as null)
        # Not in "required" AND type includes null:
        deletedAt:
          type: ["string", "null"]
          format: date-time

        # Nullable reference type
        organization:
          oneOf:
            - $ref: "#/components/schemas/Organization"
            - type: "null"

      required:
        - id
        - avatarUrl    # present, but can be null
        # bio and deletedAt are optional (not required)
        # organization is optional

The key distinction: optional means the property key may be absent from the object (controlled by required). Nullable means the property key is present but its value may be null (controlled by the type array). A field can be optional, nullable, both, or neither independently.

TypeScript Code Generation

openapi-typescript generates TypeScript types directly from an OpenAPI spec with a single CLI command — no runtime dependency.

# Install
npm install -D openapi-typescript

# Generate types from a local file
npx openapi-typescript ./openapi.yaml -o ./src/types/api.d.ts

# Generate from a URL (useful for API-first workflows)
npx openapi-typescript https://api.example.com/openapi.json -o ./src/types/api.d.ts

# Add to package.json scripts
{
  "scripts": {
    "generate:types": "openapi-typescript ./openapi.yaml -o ./src/types/api.d.ts"
  }
}

The generated file exports two main types: paths (every endpoint with its request/response shapes) and components (all schemas from components/schemas).

// Import generated types
import type { paths, components } from "./types/api"

// Extract a schema type
type User = components["schemas"]["User"]
type ApiError = components["schemas"]["ApiError"]
type CreateUserRequest = components["schemas"]["CreateUserRequest"]

// Extract endpoint-specific types
type CreateUserResponse =
  paths["/users"]["post"]["responses"]["201"]["content"]["application/json"]

// Use with openapi-fetch for a fully typed fetch client
import createClient from "openapi-fetch"
import type { paths } from "./types/api"

const client = createClient<paths>({ baseUrl: "https://api.example.com" })

// TypeScript infers request body shape and response type automatically
const { data, error } = await client.POST("/users", {
  body: {
    email: "alice@example.com",  // TypeScript enforces CreateUserRequest shape
    name: "Alice",
  },
})
// data is typed as User, error is typed as ApiError

Pair openapi-typescript with openapi-fetch (from the same project) for a typed HTTP client that enforces the correct request body shape and narrows the response type at compile time — without any runtime overhead beyond a thin fetch wrapper.

Hosting Docs with Swagger UI and Redoc

Both Swagger UI and Redoc take your openapi.yaml or openapi.json file and render it to an interactive HTML page. The simplest deployment is a static HTML file that loads the library from a CDN.

<!-- Swagger UI via CDN -->
<!DOCTYPE html>
<html>
<head>
  <title>API Docs</title>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" type="text/css"
    href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" >
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    SwaggerUIBundle({
      url: "/openapi.json",       // serve your spec file
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout"
    })
  </script>
</body>
</html>

<!-- Redoc via CDN -->
<!DOCTYPE html>
<html>
<head>
  <title>API Reference</title>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <redoc spec-url='/openapi.json'></redoc>
  <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>
</body>
</html>

For Next.js projects, serve the spec file from the public directory (public/openapi.json) and host the HTML page as a static route. The next-swagger-doc package can also generate the spec automatically from JSDoc annotations in your route handlers.

# Express.js — serve Swagger UI as middleware
npm install swagger-ui-express

import swaggerUi from "swagger-ui-express"
import yaml from "js-yaml"
import fs from "fs"

const spec = yaml.load(fs.readFileSync("./openapi.yaml", "utf8"))

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec))
// Visit http://localhost:3000/api-docs

Definitions

OpenAPI

A specification (formerly Swagger) for describing REST APIs in a machine-readable format (YAML or JSON). Defines endpoints, parameters, request/response bodies, authentication, and schemas. Version 3.1 fully adopts JSON Schema Draft 2020-12 as its schema language.

components/schemas

The schema library section of an OpenAPI document. A flat map of schema name to JSON Schema object. Schemas defined here are inert until referenced with $ref: "#/components/schemas/Name" from path items, request bodies, or response definitions.

$ref

A JSON Reference that substitutes a schema defined elsewhere. Within a file, uses a JSON Pointer fragment like #/components/schemas/User. Can point to external files with a relative path. In OpenAPI 3.1, $ref can coexist with sibling keywords like description.

openapi-typescript

A CLI tool and library that generates TypeScript type declarations from an OpenAPI 3.x spec. Produces a .d.ts file exporting paths and components types with no runtime dependency. Pairs with openapi-fetch for a fully typed HTTP client.

Swagger UI

An open-source web UI that renders an OpenAPI spec as interactive HTML documentation. Provides a "Try it out" feature for executing API requests from the browser. Distributed as a CDN bundle, npm package, or Docker image. Maintained by SmartBear.

FAQ