Linter rulesSwagger 2.0id-defined

id-defined

Since 0.9.0 · fixed by --fix

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.

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.

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

Bad. The API has no identifier.

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

Bad. The identifier is not a UUID.

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.

Related rules

Further reading