# id-defined

Source: https://apigenie.pl/docs/linter/asyncapi/rules/id-defined

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.

```yaml
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.

```yaml
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.

```yaml
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.

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

**Bad**. The identifier is not a URI.

```yaml
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.