# id-defined

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

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. Fixed by `--fix`. In the rulesets: Strict at error, All at error.

This rule checks that `info` has an identifier field, `x-id` by default, whose value is a UUID
or matches a pattern of your own.

## Rule details

Titles change, files move and two teams can call their API `Payments`. An identifier that
never changes keeps an API traceable across versions and catalogs, and the OpenAPI specification
has no field for one, so the rule looks for an extension of the info object.

The rule reports `API identifier (x-id) is missing` when the field is absent or empty, and an
issue when the value does not match the pattern.

## Configuration

An object with two properties, both required when the object is given:

- `attribute`: the name of the field; it has to start with `x-`. `x-id` by default.
- `pattern`: `uuid`, or an ECMAScript regular expression the value has to match. `uuid` by
  default.

**Configuration example**. The identifier is `x-ident`, a word of lower-case letters.

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

## Examples

**Good**. The file can be renamed, versioned or copied and the API stays the same one.

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

**Bad**. No identifier.

```yaml
openapi: 3.0.3
info:
  title: Payments
  version: 1.2.4
paths: {}
```

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

```yaml
openapi: 3.0.3
info:
  title: Payments
  version: 1.2.8
  x-id: 237849128738
paths: {}
```

## Automatic fixes

With the `uuid` pattern, `--fix` writes a new UUID v4 into a missing or invalid field. With a
pattern of your own, nothing is fixed.
