id-defined

Since 0.9.0 · fixed by --fix · In the rulesets: Strict at error, All at error

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.

The OpenAPI and AsyncAPI linters have rules of the same name, id-defined and id-defined.

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.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        id-defined: off

Related rules

Further reading

Was this helpful?