Skip to content

"Operation must define parameter {id} as expected by path" (path-params)

Last checked and updated

Every {name} in a path needs a parameter with in: path, the same name and required: true, declared on the operation or on its path item. Spectral's path-params rule reports each way this can go wrong.

The four messages you usually see

A file with three mistakes: one operation declares nothing, another misspells a name and omits required (the paths of the file, shortened; the line numbers below are the full file's):

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder        # no parameters at all
  /orders/{orderId}/items/{itemId}:
    get:
      operationId: getOrderItem
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
        - name: itemID             # the path says itemId
          in: path
          schema: { type: string }
$ apigit lint pp.yaml
  ...
  13:9   error  path-params   Operation must define parameter "{orderId}" as expected by path "/orders/{orderId}".  (paths./orders/{orderId}.get)
  22:9   error  path-params   Operation must define parameter "{itemId}" as expected by path "/orders/{orderId}/items/{itemId}".  (paths./orders/{orderId}/items/{itemId}.get)
  37:11  error  oas3-schema   "1" property must have required property "required".  (paths./orders/{orderId}/items/{itemId}.get.parameters.1)
  37:11  error  path-params   Path parameter "itemID" must have "required" property that is set to "true".  (paths./orders/{orderId}/items/{itemId}.get.parameters.1)
  37:11  error  path-params   Parameter "itemID" must be used in path "/orders/{orderId}/items/{itemId}".  (paths./orders/{orderId}/items/{itemId}.get.parameters.1)
MessageMeaningFix
Operation must define parameter "" as expected by pathThe path has {x}, no path parameter is named xDeclare it, or correct the name
Parameter "x" must be used in pathA path parameter is declared that the path does not containRename it to match, or remove it
Path parameter "x" must have "required" property that is set to "true"required is missing or falseAdd required: true
"1" property must have required property "required" (oas3-schema)The same omission, reported by the schema check; 1 is the parameter's position in the listSame fix

The rule has a few more messages for rarer cases: a parameter defined twice, the same parameter used twice in one path, and two paths that differ only in their parameter names. One misspelt name produces a pair: the path's {itemId} has no parameter, and the parameter itemID has no place in the path. Names are case sensitive.

Why required: true is not optional

A path parameter is part of the address: without a value there is no such path. The specification therefore says that for in: path the required property "is REQUIRED and its value MUST be true". An optional segment is written as two paths, /orders and /orders/{orderId}.

Declare it once per path

paths:
  /orders/{orderId}:
    parameters:
      - name: orderId
        in: path
        required: true
        description: The order's id
        schema:
          type: string
    get:
      operationId: getOrder
    delete:
      operationId: deleteOrder

Parameters on the path item apply to all of its operations, which removes the most common cause of this error: a new operation added under an existing path without copying the parameter. A shared parameter can also live under components/parameters and be referenced where needed: reusing parameters.

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