# id-defined

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

This rule checks whether the `#/info/x-id` attribute is present in an OpenAPI
schema and if it's a valid UUID.

## Rule Details

Uniquely identifying an API in tracking and managing different versions
of the API. OpenAPI, however, does not provide an "identifier" field for an
API.

The `id-defined` rule fills this gap. It ensures that ID attribute is defined
in an OpenAPI info object, and that its value matches the expected format.

## Configuration

The rule configuration must be an object with two attributes, `attribute` and
`pattern`. `attribute` specified the name of the ID attribute, and `pattern`
specifies its expected format. Neither of them can be empty or missing.

`attribute` must start with `x-`, as the ID attribute is an extension.

`pattern` value can be `uuid` which is treated as UUID regexp, or a string
representing ECMAScript regexp.

**Configuration Example**. The following configuration makes the rule look for
the `#/info/x-ident` attribute, whose value must be a sequence of one or more
lower case letters.

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

## Examples

This rule should be used whenever an OpenAPI schema is being defined. For
instance:

**Good**. Now we can rename, version or modify the schema file, or introduce
any other change, and still be able to track the API.

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

**Bad**. In the following example, it is difficult to track the evolution of
the API. Renaming a schema file, or creating a different API with the same
title will lead to ambiguities.

```yaml
openapi: 3.0.3
info:
  title: Payments
  version: 1.2.4
paths: ...
```

**Bad**. In the following example, value of the `x-id` field is not an UUID.
It makes it difficult to ensure the uniqueness of this identifier.

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

## Automatic fixes

If `pattern` is set to `uuid`, this rule becomes auto-fixing. If the linter
is invoked with the `--fix` option, it automatically generates an UUID v4 in
correct place of the schema.

## When Not to Use It

We recommend to always set this attribute.

## Compatibility

This rule is compatible with all OpenAPI 3.x version.