channel-parameters-defined

Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error

This rule checks that the parameters used in a channel address are declared in the channel’s parameters map, and that the map declares no parameters the address does not use.

Rule details

A channel address may contain parameter expressions, such as {userId} in users.{userId}.signedUp. The AsyncAPI specification requires every such expression to have a matching entry in the channel’s parameters map, whose key is the parameter name. Parameters that are declared but never used in the address are almost always leftovers from an earlier version of the address.

The channel-parameters-defined rule checks every channel defined in the root channels map and in components/channels (references to channels are checked where the channel is defined). For each channel it reports:

  • Channel parameter '<name>' is not defined for every parameter used in the address that has no entry in the parameters map,
  • Channel parameter '<name>' is not used in the channel address for every entry of the parameters map that does not appear in the address.

Channels without an address (or with address: null) are ignored, since their parameters cannot be verified.

Examples

Good. The address and the parameters map agree.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
channels:
  userSignedUp:
    address: users.{userId}.signedUp
    parameters:
      userId:
        description: Identifier of the user.

Bad. userId is used in the address but not declared, and region is declared but not used.

asyncapi: 3.0.0
info:
  title: User Events
  version: 1.0.0
channels:
  userSignedUp:
    address: users.{userId}.signedUp
    parameters:
      region:
        description: Region the user signed up in.

Automatic fixes

--fix rewrites the parameters map of every reported channel so that it matches the address: declared parameters that the address uses are kept unchanged (including references), missing parameters are added as empty Parameter objects, and unused ones are removed. The parameters are ordered as they first appear in the address. If the address uses no parameters at all, the parameters map is removed.

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-parameters-defined: off

Related rules

Last updated on View as Markdown
Was this helpful?