id-defined

Since 0.9.0 · fixed by --fix

This rule checks whether the application identifier (the root id field) is present in an AsyncAPI document, and whether its value matches the expected format.

Rule Details

Uniquely identifying an application is essential for tracking and managing different versions of its API. Titles and file names change over time, and different applications may share a title. AsyncAPI provides the root id field for this purpose; the specification requires its value to be a URI (for example a URN).

The id-defined rule ensures that the id field is defined, and that its value matches the configured pattern. The rule reports Application identifier (id) is missing when the field is absent, and Application identifier (id) has invalid format when its value does not match the pattern.

Configuration

The rule configuration must be an object with a single optional attribute, pattern, which specifies the expected format of the identifier. When given, it must be a non-empty string:

• uri (the default) - any absolute URI, i.e. a scheme followed by a colon and at least one non-whitespace character (e.g. urn:example:pets or https://your-company.com/apis/pets),
• uuid - a UUID URN, i.e. urn:uuid: followed by a UUID (e.g. urn:uuid:9c9c1d3c-3d4c-4a8e-9f54-0b2f7d7e6c11),
• any other string is treated as an ECMAScript regular expression, which must match the whole identifier.

Configuration Example. The following configuration requires the identifier to be a UUID URN.

version: "1.0"
commands:
  lint:
    asyncapi:
      rules:
        id-defined:
          - error
          - pattern: uuid

Configuration Example. The following configuration requires the identifier to be a URN in the your-company namespace.

version: "1.0"
commands:
  lint:
    asyncapi:
      rules:
        id-defined:
          - error
          - pattern: "urn:your-company:[a-z-]+"

Examples

Good. The application can be tracked independently of its title and version.

asyncapi: 3.0.0
id: urn:uuid:9c9c1d3c-3d4c-4a8e-9f54-0b2f7d7e6c11
info:
  title: Pet Events
  version: 1.2.8

Bad. There is no identifier, so it is difficult to track the evolution of the API. Renaming the file, or creating a different API with the same title, leads to ambiguities.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.2.4

Bad. The identifier is not a URI.

asyncapi: 3.0.0
id: pet events
info:
  title: Pet Events
  version: 1.2.8

Automatic fixes

If pattern is uri or uuid, this rule is auto-fixing. When the linter is invoked with the --fix option, it sets the id field to a newly generated UUID URN (urn:uuid: followed by a random UUID v4). An existing identifier with an invalid format is replaced. Identifiers checked against a custom regular expression are not fixed.

When Not to Use It

We recommend to always set the application identifier.

Compatibility

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

Related rules

• audience-defined
• info-defined