# id-defined

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

This rule checks whether the info object of a Swagger 2.0 document has an
identifier extension (`x-id` by default), and whether its value has the
expected format (a UUID by default).

## Rule Details

A stable identifier makes it possible to track an API across renames, new
versions and moved files. Swagger 2.0 does not provide an identifier field for
an API, so the rule requires an `info` extension to hold it.

The rule reports:

- `API identifier (x-id) is missing` when the extension is absent,
- `API identifier (x-id) has invalid format` when its value is not a string,
  or does not fully match the expected pattern.

The name in parentheses is the configured attribute.

## Configuration

The rule accepts an object with two options. When options are given, both are
required:

- `attribute`: the name of the extension that holds the identifier. It must
  not be empty and must start with `x-`. Default: `x-id`.
- `pattern`: the expected format of the identifier. `uuid` (the default)
  accepts UUIDs in the `8-4-4-4-12` hexadecimal form, any other value is an
  ECMAScript regular expression that must match the whole identifier.

**Configuration Example**. The rule looks for the `info.x-ident` extension,
whose value must be one or more lower case letters.

```yaml
version: "1.0"
commands:
  lint:
    swagger:
      rules:
        id-defined:
          - error
          - attribute: x-ident
            pattern: "[a-z]+"
```

## Examples

**Good**. The API can be tracked whatever happens to its title or file name.

```yaml
swagger: '2.0'
info:
  title: Payments
  version: 1.2.8
  x-id: 123e4567-e89b-12d3-a456-426614174000
paths: {}
```

**Bad**. The API has no identifier.

```yaml
swagger: '2.0'
info:
  title: Payments
  version: 1.2.4
paths: {}
```

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

```yaml
swagger: '2.0'
info:
  title: Payments
  version: 1.2.8
  x-id: 237849128738
paths: {}
```

## Automatic fixes

The rule is auto-fixable only while `pattern` is `uuid`. Then `--fix` sets the
configured attribute of the info object to a newly generated UUID v4, both
when the attribute is missing and when its value is invalid. With a custom
pattern the issues are reported but not fixed.

## When Not to Use It

We recommend to always enable this rule.

## Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x and AsyncAPI
documents are linted by the OpenAPI and AsyncAPI linters, which have their own
`id-defined` rules.