Skip to content

"Every operation must have unique operationId" (operation-operationId-unique)

Last checked and updated

Two operations in the document have the same operationId. The OpenAPI specification says the id "MUST be unique among all operations described in the API". The linter rule is Spectral's operation-operationId-unique, an error by default.

How it is reported

paths:
  /orders:
    get:
      operationId: getOrders
  /orders/{orderId}:
    get:
      operationId: getOrders
$ apigit lint dup.yaml
  30:20  error  operation-operationId-unique  Every operation must have unique "operationId".  (paths./orders/{orderId}.get.operationId)

The finding is on the second use: line 30 of the full file, the operation GET /orders/{orderId}. The first one (line 14) is not marked; search the file for the id to find it.

Why it matters beyond the linter

Tools may use the id as a name. A client generator that makes a method from each one has to do something with a duplicate: merge, rename or fail, depending on the generator. Some documentation tools build links from ids, and anything that selects an operation by id may reach only one of the pair.

How it happens

CauseFix
An operation was copied and its id not changedRename the copy
The list and the single-item operation got the same name (getOrders twice)listOrders and getOrder
The same id under two paths or two versions (/v1/orders, /v2/orders)Include what differs: listOrdersV2
Files merged from two teamsPrefix by area: billingListInvoices

A scheme that does not collide

verb + resource, with the list and the item told apart by the verb and the number:

OperationoperationId
GET /orderslistOrders
POST /orderscreateOrder
GET /orders/{orderId}getOrder
PATCH /orders/{orderId}updateOrder
DELETE /orders/{orderId}deleteOrder
GET /orders/{orderId}/itemslistOrderItems

More on choosing ids, and the characters to avoid: operationId in OpenAPI.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish