# OpenAPI Specification (OAS)

> A comprehensive, multi-section guide to the OpenAPI Specification (OAS), detailing root structures, paths, component registries, and version diffs.

Source: https://apiguide.dev/specifications/openapi
Current version: 3.2.1
Official source: https://spec.openapis.org/oas/v3.2.1.html
Updated: 2026-10-14

## Core Architecture of OpenAPI

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs. It allows both humans and computers to discover and understand the capabilities of a service without access to source code, documentation, or network traffic inspection.

An OpenAPI document is structurally composed of several key root nodes:

### OpenAPI Document Architecture

An OpenAPI document is structured to document all aspects of a REST API contract:
1. **Metadata & Entrypoints (`info` & `servers`)**: Defines descriptive metadata (names, licensing, contacts) and the environment base URLs (development, staging, production).
2. **Routings & Paths (`paths`)**: Maps each relative URI endpoint (e.g., `/orders/{orderId}`) to its supported HTTP methods (Operations).
3. **Operations Schema**: Each method specifies parameters (query, header, path), request body payload structures, and response maps (HTTP status codes matching specific payload schemas).
4. **Reusable Registry (`components`)**: Holds reusable schemas, security mechanisms (OAuth2, Bearer JWT), and parameters that can be reference-pointer linked (`$ref`) throughout the document.

---

## 1. Root-Level Nodes Explained

### Info Object (`info`)
Contains metadata about the API. This is used by developers and documentation generators to understand the context of the service.
* **`title`** (Required): The name of your API.
* **`version`** (Required): The version of your API implementation (not to be confused with the OpenAPI Spec version).
* **`description`**: Extended explanation, supporting CommonMark Markdown.

```yaml
info:
  title: Payments Processing Gateway
  version: "1.4.0"
  description: Secure API endpoints to authorize, process, and refund credit card transactions.
```

### Servers Object (`servers`)
An array of servers providing connectivity information. By defining these, interactive documentation suites (like Swagger UI or Redocly) allow users to test live API calls.
* **`url`** (Required): The base address of the environment.
* **`description`**: A short label describing the environment.
* **`variables`**: Custom parameters (e.g. letting users swap subdomains).

```yaml
servers:
  - url: https://api.payments.apiguide.dev/v1
    description: Production gateway
  - url: https://sandbox-api.payments.apiguide.dev/v1
    description: Testing sandbox environment
```

---

## 2. Paths & Operations (`paths`)

The `paths` object forms the core routing table of the API. Each path item represents a unique endpoint (URI) relative to the server base URL.

### Path Parameters
Endpoints can define variable parameters using curly braces (e.g., `/users/{userId}`). These must be declared inside the `parameters` array of the path or the specific operation.

### HTTP Methods (Operations)
Each path item supports the standard HTTP methods as fixed fields (`get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace`, and from 3.2 `query`). None of an operation's fields is strictly required, but a useful one defines:
* **`operationId`**: A globally unique identifier for the action, used by SDK code generators as the method name.
* **`parameters`**: Operation-level parameters passed in `query`, `header`, `path`, or `cookie`.
* **`requestBody`**: The payload sent during POST, PUT, or PATCH.
* **`responses`**: A map of status codes to response schemas.

```yaml
paths:
  /orders/{orderId}:
    get:
      summary: Retrieve Order Details
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: include_refunds
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Order details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
```

---

## 3. Reusable Components (`components`)

The `components` object serves as a centralized registry for objects that are referenced repeatedly throughout your API description. Objects declared here have no effect unless they are referenced elsewhere using JSON Reference pointers (`$ref`).

Common Component Sub-registries:
* **`schemas`**: Models describing request and response payloads.
* **`securitySchemes`**: Authentication mechanisms (Basic, Bearer JWT, OAuth2, API Keys).
* **`parameters`**: Reusable path, query, or header parameters (e.g., standard pagination query parameters).
* **`headers`**: Common response headers (e.g., rate-limiting response headers).

```yaml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Order:
      type: object
      required:
        - id
        - total_amount
      properties:
        id:
          type: string
          format: uuid
        total_amount:
          type: number
          minimum: 0.01
```

---

## 4. Key Differences: OpenAPI 3.0 vs. OpenAPI 3.1

The shift from OpenAPI 3.0 to 3.1 introduced critical modifications designed to align the specification fully with standard JSON Schema draft specifications.

| Feature | OpenAPI 3.0 | OpenAPI 3.1 |
| :--- | :--- | :--- |
| **JSON Schema** | Subset of JSON Schema Draft 5 | Full alignment with JSON Schema Draft 2020-12 |
| **Nullable types** | Uses `nullable: true` | Uses arrays like `type: [string, "null"]` |
| **`exclusiveMinimum`** | Boolean value (works with `minimum`) | Numeric value (replaces `minimum` when exclusive) |
| **Webhooks** | Not natively supported | First-class support via root-level `webhooks` node |
| **File uploads** | `type: string` with `format: binary` or `format: byte` | `contentMediaType` and `contentEncoding` from JSON Schema |

---

## 5. What OpenAPI 3.2 Added

OpenAPI 3.2.0 was published on 19 September 2025, and 3.2.1, a patch release, on 10 September 2026. Patch releases fix errors and clarify wording without changing the feature set, so tooling makes no distinction between 3.2.0 and 3.2.1. Minor versions add features, and the specification reserves the right to make low-impact breaking changes in them, so migrating from 3.1 is not guaranteed to be a one-line edit. The 3.1 line continues as 3.1.2 for toolchains that have not moved. The additions that change how you describe an API:

| Area | 3.2 addition |
| :--- | :--- |
| **Methods** | A `query` field on the Path Item for the [`QUERY`](/methods/query) method, and `additionalOperations`, a map keyed by method name for anything else (for example WebDAV's [`COPY`](/methods/copy)). It must not repeat a method that has its own fixed field. |
| **Query strings** | `in: "querystring"` describes the entire query string as one parameter, with its shape given by `content`, typically `application/x-www-form-urlencoded`. It cannot be combined with `in: "query"` parameters on the same operation. |
| **Streaming** | `itemSchema` on the Media Type Object describes each item in a sequential media type such as `application/jsonl`, `application/x-ndjson`, `application/json-seq` or `text/event-stream`, rather than the stream as a whole. |
| **Tags** | `parent` nests one tag under another, and `kind` categorizes a tag (`nav`, `badge`, `audience` are the common values). |
| **Document identity** | A root-level `$self` gives the document its own URI, which also serves as its base URI for resolving relative references. |
| **Security** | A `deviceAuthorization` OAuth flow, `oauth2MetadataUrl` pointing at RFC 8414 authorization server metadata, and `deprecated` on a security scheme. |

```yaml
openapi: 3.2.1
paths:
  /orders/search:
    query:
      operationId: searchOrders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderFilter'
      responses:
        '200':
          description: Matching orders, one per line
          content:
            application/jsonl:
              itemSchema:
                $ref: '#/components/schemas/Order'
```

If you write new descriptions, target 3.2 when your toolchain supports it, because `itemSchema` and `query` describe things 3.1 can only document in prose. Check your generators and validators first: support for each minor version lands tool by tool. To change a description you do not own, such as one generated from code, layer edits on top with an [OpenAPI Overlay](/specifications/openapi-overlay) rather than forking the file.