channel-servers-in-servers

Since 0.12.0 · In the rulesets: Recommended at error, Strict at error, All at error

This rule checks that the servers of a channel under the root channels are references to servers under the root servers.

Rule details

A channel’s servers lists the servers it is available on. The specification requires each entry of a channel under the root channels to be a reference to a server under the root servers, so that the document says where the channel is. A reference to components/servers, or to another file, is reported. A root entry that is a reference to a channel under components/channels is checked as that channel, once however many entries name it; a channel under components/channels that no root entry names may refer to any server. A root entry that refers to another file is not checked.

The rule reports Channel server '<ref>' must be a reference to a server of the root servers ('#/servers/...') on each server of the channel that is not under the root servers.

The rule is the counterpart of the AsyncAPI parser’s asyncapi3-required-channel-servers-unambiguity, which accepts a reference to another file’s servers and skips root entries that are references.

Turn the rule off for a spec that keeps its servers in another file: the linter does not read other files, and asyncapi validate accepts the reference.

Examples

Good.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
servers:
  production:
    host: broker.example.com:9092
    protocol: kafka
channels:
  petAdopted:
    address: pets.adopted
    servers:
      - $ref: '#/servers/production'

Bad. The channel names a server of components.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
channels:
  petAdopted:
    address: pets.adopted
    servers:
      - $ref: '#/components/servers/production'
components:
  servers:
    production:
      host: broker.example.com:9092
      protocol: kafka

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.asyncapi has the details.

commands:
  lint:
    asyncapi:
      rules:
        channel-servers-in-servers: off

Related rules

Further reading

Was this helpful?