id-defined

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.

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.

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

Bad. No identifier.

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

Bad. The value is not a UUID.

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.

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.rules has the details.

commands:
  lint:
    rules:
      id-defined: off
Was this helpful?