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 missingwhen the extension is absent,API identifier (x-id) has invalid formatwhen 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 withx-. Default:x-id.pattern: the expected format of the identifier.uuid(the default) accepts UUIDs in the8-4-4-4-12hexadecimal 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