"Potentially unused component has been detected" (oas3-unused-component)
Last checked and updated
A linter found an entry under components (a schema, a parameter, a response) that no $ref in the document points to. The document is valid; this is a warning from the Spectral rule oas3-unused-component. "Potentially" is deliberate: the linter cannot know about references from other files or from outside the description.
How it is reported
$ apigit lint good31.yaml
57:12 warn oas3-unused-component Potentially unused component has been detected. (components.schemas.Paging)
The path at the end names the component: components.schemas.Paging, defined at line 57.
Three causes, three different fixes
A leftover. The operation that used it was removed or now uses another schema. Delete the component: an unused schema can still show up in generated documentation or generated code, where it looks like part of the API.
A typo in a reference. The warning then comes with an error:
18:25 error invalid-ref '#/components/schemas/Ordr' does not exist (paths./orders.get.responses.200.content.application/json.schema.items.$ref)
21:11 warn oas3-unused-component Potentially unused component has been detected. (components.schemas.Order)
Order is unused because the reference says Ordr. Fix the reference and both findings go: see finding a broken $ref.
It is used, from somewhere the linter does not see. A shared file of components that other descriptions reference, or a schema used only by code generation or by an extension. The warning is expected there.
Switching the rule off, or down
In the Spectral rule set the linter reads (.spectral.yaml in the working directory):
extends: ["spectral:oas"]
rules:
oas3-unused-component: off
hint instead of off keeps the finding visible without it counting as a warning. For one shared-components file, an override limited to that file keeps the rule active everywhere else (the extends line has to be in the same file, or the rule is unknown there):
extends: ["spectral:oas"]
overrides:
- files: ["shared/components.yaml"]
rules:
oas3-unused-component: off
In CI
With the default settings a warning does not fail the run: apigit lint exits with an error only for findings at severity error, unless --fail-severity warn is given. A team that wants no dead components can set that flag once the existing ones are cleaned up.