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.

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.

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.

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.

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.