Appear Logo

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.