Appear Logo

Appear the product is winding down. Continue at ctxpipe.ai — the engineering context layer for your org. Tools on this site remain available.

OpenAPI reference

OpenAPI Glossary

Concise OpenAPI glossary of core terms engineers need when reading and writing API specifications.

Prefer the interactive hub? Open in Specs Hub

Glossary {#glossary-openapi}

OpenAPI Specification Glossary

A practical glossary of the most important terms you’ll encounter when working with OpenAPI.

OpenAPI

The standardized specification for describing REST APIs. Defines how to represent endpoints, parameters, request/response bodies, authentication, and more. Current major versions: 3.0, 3.1, 3.2.

Info Object

Top-level metadata about the API (title, description, version, terms of service, contact, license).

Servers

An array of base URLs where the API is hosted. Supports variables for templating (e.g., {environment}).

Paths Object

Defines all available API endpoints and the operations (GET, POST, etc.) on each path.
Example: /users/{id} with operations for GET /users/{id} and DELETE /users/{id}.

Operation

An individual HTTP method on a path (e.g., GET /pets). Contains parameters, request body, responses, and tags.

Parameters

Inputs to operations that are not in the request body. Types:

  • path (/users/{id})
  • query (/users?id=123)
  • header (X-Request-ID)
  • cookie (session_id)

Request Body

The payload of an operation, typically in application/json but can include multipart/form-data, application/xml, or other media types.

Responses

The expected results of an operation. Each response is keyed by HTTP status code (200, 400, default) and includes description, headers, and content.

Components

A reusable object store. Can contain:

  • schemas (data models)
  • responses (reusable responses)
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks

Schema

Defines the shape of input/output data, typically using JSON Schema keywords (type, properties, required, oneOf, etc.). Used for parameters, request bodies, and responses.

Example / Examples

Sample payloads that illustrate the use of parameters, requests, or responses.

  • example: single inline value.
  • examples: multiple named samples with summaries.

$ref

Reference keyword for reusing objects in the spec.
Example:

$ref: '#/components/schemas/User'

Tags

Keywords used to group operations logically. Commonly shown in rendered docs (e.g., all “user” operations together).

Security Schemes

Defines how authentication is handled. Types include:

  • apiKey (header, query, or cookie)
  • http (basic, bearer)
  • oauth2
  • openIdConnect

Security Requirement

Applies defined security schemes either globally (all operations) or locally (per operation).

Callbacks

Describe asynchronous, out-of-band requests that the server may initiate back to the client.
Example: webhooks for events.

Webhooks (OAS 3.1+)

Define incoming requests that an API consumer should expect to receive, effectively formalizing webhook definitions in OpenAPI.

Discriminator

A hint used with oneOf/anyOf polymorphism to indicate which schema definition should be used.
Example: a type field that selects between Car, Truck, Bike.

oneOf, anyOf, allOf

JSON Schema constructs:

  • oneOf: data must match exactly one schema.
  • anyOf: data can match any (one or more).
  • allOf: data must match all schemas (composition).

Nullable

Deprecated in OAS 3.1. In 3.0, nullable: true indicated that a value could be null. In 3.1, use:

type: [string, "null"]

### Content
Describes media types (MIME types) and schemas for request/response payloads.  
**Example:**
```yaml
application/json:
  schema:
    $ref: '#/components/schemas/User'

Media Type Object

Defines a schema and examples for a specific content type (e.g., application/json).

Defines metadata returned in a response or expected in a request. Can be reused under components/headers.

Defines relationships between responses and subsequent requests.
Example: a userId from POST /users can be linked to GET /users/{id}.

OperationId

A unique string identifying an operation. Often used by code generators to name functions.

External Docs

An optional object for linking to additional external documentation for a schema, operation, or the entire API.

Specification Extensions (x-)

Custom vendor extensions prefixed with x-. Not part of the spec, but widely used for custom tooling.
Example: x-codegen-settings.

Formats

Refinements for primitive types in JSON Schema.
Examples: date-time, uuid, email, binary.

Default Response

A fallback response definition used when a specific status code isn’t covered.
Example:

default:
  description: Unexpected error

OpenAPI Version

Declared at the root of the document (openapi: 3.1.0). Determines supported features and compatibility.

JSON Schema

The underlying schema language used in OpenAPI to describe data structures. OAS 3.1 fully aligns with JSON Schema 2020-12 (with caveats).

Specification Document

The .yaml or .json file (or set of files) that defines the API using the OpenAPI spec. Sometimes referred to as the contract.