OpenAPI Operation Object Fields

The OpenAPI 3.1 Operation Object

In an OpenAPI document, each HTTP method under a path is an Operation Object. It bundles the parameters, request body, possible responses and metadata for one call. This reference lists every field of the 3.1 Operation Object with its JSON type and requirement, plus a live search.

How it works

An Operation sits inside a Path Item, keyed by the lowercase method name:

paths:
  /pets/{id}:
    get:
      operationId: getPet
      tags: [pets]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: A pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        "404":
          description: Pet not found

Only the responses field is required. The parameters array is merged with any path-level parameters; requestBody replaces the older body parameter from Swagger 2.0; and callbacks define out-of-band webhooks the API may send.

Field-by-field guide

operationId — string, optional but strongly recommended

A unique identifier for the operation across the whole document. Code generators use it directly as a method name in generated client libraries, so treat it like a function name: camelCase, no spaces, unambiguous.

operationId: createOrder    # becomes client.createOrder() in generated code

tags — array of strings

Groups operations in the rendered documentation and in generated SDKs. Matching a tag to a top-level tags entry lets you add a description and external docs link for the group.

parameters — array

Each Parameter Object describes one input in path, query, header, or cookie. Path parameters that appear in the URL template ({id}) must be declared here or at the path level with required: true.

requestBody — object

Replaces Swagger 2.0’s body parameter. Supports multiple media types via content so one endpoint can accept both JSON and form data:

requestBody:
  required: true
  content:
    application/json:
      schema: { $ref: '#/components/schemas/NewPet' }
    application/x-www-form-urlencoded:
      schema: { $ref: '#/components/schemas/NewPetForm' }

responses — object, required

The only mandatory field. Keys are HTTP status codes (as strings: "200", "404") or the wildcard "default". Every operation must declare at least one response. Code generators use the "200" or "201" response schema to type the return value of the generated method.

callbacks — object

Maps a callback name to a map of runtime expressions to Path Item Objects. Useful for webhook-style APIs where the server calls back a client URL supplied at request time.

security — array

When present, overrides the global security requirement for this operation only. An empty array (security: []) marks an operation as public even when the document-level default requires auth.

deprecated — boolean

Set to true to signal that the operation will be removed in a future version. Rendered as a strikethrough in most documentation renderers. The operation continues to function; the flag is informational.

servers — array

Overrides the root and path-level servers array. Useful when one operation must be called against a different base URL (for example, a separate media upload endpoint on a CDN host).

Tips and notes

• Give every operation a unique operationId so generators produce clean names and SDK maintainers can write targeted changelog notes.
• An operation-level security: [] (empty array) is the correct way to make a single operation public when the document default requires authentication. Omitting security entirely inherits the document default; a non-empty array replaces it.
• In OpenAPI 3.1 (unlike 3.0), schemas inside operations are full JSON Schema 2020-12 — you can use if/then/else, $defs, unevaluatedProperties, and prefixItems alongside the standard type and properties.
• x- extension fields are allowed on the Operation Object and are widely used by tools: x-codeSamples (Redoc), x-internal (hide from public docs), x-amazon-apigateway-integration (AWS API Gateway).