Skip to content

"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.

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