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 withx-.x-idby default.pattern:uuid, or an ECMAScript regular expression the value has to match.uuidby 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