channel-parameters-defined (AsyncAPI linter rule)

channel-parameters-defined

Since 0.9.0 · fixed by --fix

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.

Configuration

None.

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

When the linter is invoked with the --fix option, this rule 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.

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with AsyncAPI 3.x documents. AsyncAPI 2.x documents are rejected by the reader and are not linted.