Rule Name Conventions

If adding a new rule to the validator, use these conventions to determine the most appropriate name for the rule.

Conventions

• All rule names MUST be prefixed with ibm-

• All rule names MUST be lower-kebab-case (even if they include an OpenAPI field - e.g. operationId-exists would not comply)

• All rule names SHOULD maintain a level of consistency with existing Spectral rules, defined as the following:

  • Rule names MUST NOT be named in the "negative", i.e. they should be named after the "rule" not the "problem" (e.g. missing-operation-summary would not comply but operation-summary or no-content-type-header would)
  • Rule names SHOULD be named topically, i.e. they should use a simple noun to describe what is being validated (e.g. security-schemes), OR they SHOULD be named in the "positive", i.e. they should describe the rule we are enforcing (e.g. no-ref-siblings). Topical names SHOULD generally be favored
  • Rule names that check for the existence/definition of a field should be named after the field (e.g. operation-summary means "operation must have a value provided for the 'summary' field")

• When distinguishing generalized rules that incorporate multiple validations with specialized rules, a suffix SHOULD be used in the name for specialized rules.

  • Suffixes SHOULD be standardized for consistency
  • We'll accumulate a list of common suffixes here as we modify various rule names:
    • -casing-convention
    • -naming-convention
    • -convention
    • -missing
    • -style

• Rule names SHOULD NOT abbreviate API terminology unless there is OpenAPI precedent (e.g. enum would comply but param would not)