In OpenAPI 3.x, what does an operation object contain and what is operationId for?

middlemust knowfreq 62%

answer

One method on one path
Inputs, outputs, docs, lifecycle
Machine name, not a wire value
Unique across the document, drives codegen

basics

~20 s

An OpenAPI operation object describes one HTTP method on one path: tags, summary, description, operationId, parameters, requestBody, responses, callbacks, deprecated, security and servers. operationId is a document-unique name that tooling uses to identify the operation, typically as the generated method name.

solid answer

~40 s

An operation object sits under a path item keyed by the HTTP method — get, post, put, patch, delete, head, options, trace. It carries documentation (summary, description, externalDocs), grouping (tags), the inputs (parameters and, for methods with a body, requestBody), the outputs (responses, required in 3.0), plus callbacks, deprecated, a security override and a servers override. operationId is an optional but effectively mandatory-in-practice string that must be unique across the entire document. Generators turn it into the client method name and server stub name, Link objects reference operations by it, and test and gateway tooling keys off it. Because it leaks into generated code, renaming an operationId is a breaking change for SDK consumers even though the HTTP contract is untouched.

An operation object sits under a path item keyed by the HTTP method — `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `trace`. It carries documentation (`summary`, `description`, `externalDocs`), grouping (`tags`), the inputs (`parameters` and, for methods with a body, `requestBody`), the outputs (`responses`, required in 3.0), plus `callbacks`, `deprecated`, a `security` override and a `servers` override. `operationId` is an optional but effectively mandatory-in-practice string that must be unique across the entire document. Generators turn it into the client method name and server stub name, `Link` objects reference operations by it, and test and gateway tooling keys off it. Because it leaks into generated code, renaming an operationId is a breaking change for SDK consumers even though the HTTP contract is untouched.

code

yaml · 24 lines

yaml

paths:
  /orders:
    parameters:
      - name: X-Tenant
        in: header
        required: true
        schema:
          type: string
    post:
      tags: [orders]
      summary: Create an order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: Created
        '422':
          description: Validation failed
      deprecated: false

go deeper

for a junior

Recall that one operation object equals one HTTP method on one path, and that it holds parameters, requestBody and responses.

for a middle

Explain every field and why it exists, and be precise that operationId is a tooling identity that must be unique across the whole document.

for a senior

Demonstrate that operationId is published surface: renaming it breaks generated SDKs, so it needs lint enforcement and the same review discipline as a public method name.

for a principal

Own the conventions across teams — naming rules for operationIds, tag taxonomy for the portal, and how deprecation flags feed a documented endpoint lifecycle.

Where an operation object lives

Under paths, each templated URL maps to a Path Item Object. Inside that path item, each HTTP method the resource supports is a key whose value is an Operation Object: get, put, post, delete, options, head, patch, trace. So the triple (path, method, operation object) is the unit that corresponds to one endpoint.

Fields of the operation object

tags — an array of tag names used by documentation renderers to group operations into sections. Tags may also be declared at the document root to attach descriptions and ordering.
summary and description — short and long human documentation; description supports CommonMark.
externalDocs — a pointer to prose documentation elsewhere.
operationId — the unique machine name for this operation (see below).
parameters — path, query, header and cookie inputs for this operation. These are merged with any parameters declared on the enclosing path item; an operation-level entry with the same name and in replaces the inherited one.
requestBody — the payload, for methods where a body is meaningful.
responses — a map from status code to Response Object. Required in OpenAPI 3.0; 3.1 relaxed it to optional.
callbacks — a map of out-of-band requests the API will make back to the caller as a consequence of this operation.
deprecated — a boolean; documentation tools render the operation struck through, and generators typically emit a deprecation annotation.
security — overrides the document-level requirements for this one operation, including opting out.
servers — overrides the path item's or the document's base URLs for this operation.

What operationId is for

operationId is a case-sensitive string that MUST be unique among all operations described in the document. The specification itself does not require it to be present, but nearly every toolchain wants it:

Code generation. openapi-generator and similar tools derive the client method name and server stub name from it. No operationId means the generator falls back to a synthesized name built from the method and path — something like ordersOrderIdGet — which is unstable and unreadable.
Link objects. A Link Object references a target operation either by operationId or by operationRef (a JSON pointer). The operationId form is the readable one.
Everything else. API gateways, contract-test harnesses, mock servers, coverage reports and analytics dashboards use it as the stable identity of an endpoint.

Because the spec recommends following common programming naming conventions, getOrder, listOrders, createOrder are typical — lowerCamelCase verbs that read as method names in the generated SDK.

The consequence people miss

operationId is part of your published contract even though it never appears on the wire. Rename getOrder to fetchOrder and every regenerated SDK breaks at compile time for consumers, while the HTTP request is byte-for-byte identical. Treat it with the same care as a public method name: choose it once, and let linting enforce presence and uniqueness. Spectral's default rule set, for instance, flags missing and duplicate operation ids.

Inheritance from the path item

Two path-item fields feed into every operation beneath them. parameters are inherited and may be overridden per operation by matching name + in. servers are inherited and overridden wholesale. Nothing else cascades: a description on the path item does not become the operation's description, and there is no path-item-level security.

Reading it in an interview

A good answer walks the object top to bottom and pairs each field with why it exists: tags for docs, operationId for tooling, parameters and requestBody for the input contract, responses for the output contract, security for authorization, deprecated for lifecycle. A weak answer describes only responses and treats the rest as boilerplate the generator writes.

## Where an operation object lives Under `paths`, each templated URL maps to a Path Item Object. Inside that path item, each HTTP method the resource supports is a key whose value is an Operation Object: `get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace`. So the triple (path, method, operation object) is the unit that corresponds to one endpoint. ## Fields of the operation object - `tags` — an array of tag names used by documentation renderers to group operations into sections. Tags may also be declared at the document root to attach descriptions and ordering. - `summary` and `description` — short and long human documentation; `description` supports CommonMark. - `externalDocs` — a pointer to prose documentation elsewhere. - `operationId` — the unique machine name for this operation (see below). - `parameters` — path, query, header and cookie inputs for this operation. These are *merged* with any `parameters` declared on the enclosing path item; an operation-level entry with the same `name` and `in` replaces the inherited one. - `requestBody` — the payload, for methods where a body is meaningful. - `responses` — a map from status code to Response Object. Required in OpenAPI 3.0; 3.1 relaxed it to optional. - `callbacks` — a map of out-of-band requests the API will make back to the caller as a consequence of this operation. - `deprecated` — a boolean; documentation tools render the operation struck through, and generators typically emit a deprecation annotation. - `security` — overrides the document-level requirements for this one operation, including opting out. - `servers` — overrides the path item's or the document's base URLs for this operation. ## What operationId is for `operationId` is a case-sensitive string that MUST be unique among all operations described in the document. The specification itself does not require it to be present, but nearly every toolchain wants it: - **Code generation.** openapi-generator and similar tools derive the client method name and server stub name from it. No `operationId` means the generator falls back to a synthesized name built from the method and path — something like `ordersOrderIdGet` — which is unstable and unreadable. - **Link objects.** A Link Object references a target operation either by `operationId` or by `operationRef` (a JSON pointer). The `operationId` form is the readable one. - **Everything else.** API gateways, contract-test harnesses, mock servers, coverage reports and analytics dashboards use it as the stable identity of an endpoint. Because the spec recommends following common programming naming conventions, `getOrder`, `listOrders`, `createOrder` are typical — lowerCamelCase verbs that read as method names in the generated SDK. ## The consequence people miss `operationId` is part of your published contract even though it never appears on the wire. Rename `getOrder` to `fetchOrder` and every regenerated SDK breaks at compile time for consumers, while the HTTP request is byte-for-byte identical. Treat it with the same care as a public method name: choose it once, and let linting enforce presence and uniqueness. Spectral's default rule set, for instance, flags missing and duplicate operation ids. ## Inheritance from the path item Two path-item fields feed into every operation beneath them. `parameters` are inherited and may be overridden per operation by matching `name` + `in`. `servers` are inherited and overridden wholesale. Nothing else cascades: a `description` on the path item does not become the operation's description, and there is no path-item-level `security`. ## Reading it in an interview A good answer walks the object top to bottom and pairs each field with why it exists: tags for docs, operationId for tooling, parameters and requestBody for the input contract, responses for the output contract, security for authorization, deprecated for lifecycle. A weak answer describes only `responses` and treats the rest as boilerplate the generator writes.

What happens to code generation if you omit operationId?
Generators synthesize a name from the HTTP method and path, producing something like `ordersOrderIdGet`. It compiles, but it is unreadable and unstable: adding a path segment silently renames the generated method. Most teams lint for a present, unique operationId on every operation.
How do path-item parameters interact with operation-level ones?
They are merged. A parameter declared on the path item applies to every operation under that path; an operation-level parameter with the same `name` and `in` pair overrides the inherited definition. Duplicates that differ in name or location simply add up.
Is renaming an operationId a breaking change?
Not on the wire — the request and response are unchanged — but yes for consumers using a generated SDK, because the method name changes and their code stops compiling. Treat operationIds as published API surface and version them deliberately.
What does the deprecated flag on an operation actually do?
It is declarative metadata: documentation renderers mark the operation as deprecated and generators typically emit a language-level deprecation annotation on the client method. It changes no runtime behaviour — the server must still decide when to remove or reject the endpoint.

saying these in an interview costs you the question

Thinks operationId is sent in the HTTP request
Says renaming operationId is always safe
Believes responses is optional in OpenAPI 3.0
Assumes path-item parameters are ignored by operations
Can only name responses among the operation fields

In OpenAPI 3.x, what does an operation object contain and what is operationId for?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~3 min

Where an operation object lives

Fields of the operation object

What operationId is for

The consequence people miss

Inheritance from the path item

Reading it in an interview

▾common follow-ups4 questions

▾red flags5 flags

§ context

▾related questions6 questions

▾related topics3 topics

Where an operation object lives

Fields of the operation object

What operationId is for

The consequence people miss

Inheritance from the path item

Reading it in an interview

answer

go deeper

context