"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)
| Message | Meaning | Fix |
|---|---|---|
| Operation must define parameter "" as expected by path | The path has {x}, no path parameter is named x | Declare it, or correct the name |
| Parameter "x" must be used in path | A path parameter is declared that the path does not contain | Rename it to match, or remove it |
| Path parameter "x" must have "required" property that is set to "true" | required is missing or false | Add 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 list | Same 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.