schema-enum-naming

Since 0.9.0 · In the rulesets: Strict at error, All at error

This rule ensures that the string values of enum lists adhere to a predefined naming convention.

Rule details

Enum values are spelled by clients, in code and in requests, so a client author who has seen one should be able to spell the next.

The schema-enum-naming rule checks the enum list of every typed object of a Swagger 2.0 document: schemas, non-body parameters, response headers and items objects (objects with a $ref are checked where they are defined). For every string value that is not in the expected convention, it reports Schema enum value '<value>' is not in the '<convention>' convention, where <convention> is the display name of the convention (e.g. CONST_CASE). Values of other types (numbers, booleans, …) are ignored.

The recognized naming conventions are:

  • CONST_CASE (also UPPER_CASE and SCREAMING_SNAKE_CASE) - THIS_IS_CONST_CASE
  • camelCase - thisIsCamelCase, also with acronyms (userID)
  • camelCaseStrict - thisIsCamelCase, but no two capitals in a row (userId, not userID)
  • kebab-case - this-is-kebab-case
  • PascalCase - ThisIsPascalCase, also with acronyms (HTTPServer)
  • PascalCaseStrict - ThisIsPascalCase, but no two capitals in a row (HttpServer, not HTTPServer)
  • Header-Case - This-Is-Header-Case
  • snake_case - this_is_snake_case

The default convention is CONST_CASE.

The OpenAPI linter has a rule of the same name, schema-enum-naming, for OpenAPI 3.x documents.

Turn the rule off when the API follows no naming convention for enum values.

Configuration

The configuration block is a naming convention name (see the “Rule details” section for a list of recognized names).

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        schema-enum-naming: [warning, kebab-case]

Examples

Good. With the default configuration.

swagger: '2.0'
info:
  title: Users
  version: 1.0.0
paths:
  /users:
    get:
      parameters:
        - name: sort
          in: query
          type: string
          enum: [ASCENDING, DESCENDING]
      responses:
        '200':
          description: Users
definitions:
  UserStatus:
    type: string
    enum:
      - ACTIVE
      - INACTIVE
      - BLOCKED

Bad. To use UserStatus properly, a consumer must always consult the documentation.

swagger: '2.0'
info:
  title: Users
  version: 1.0.0
paths: {}
definitions:
  UserStatus:
    type: string
    enum:
      - activeStatus
      - inactive_status
      - BLOCKED_STATUS

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:
        schema-enum-naming: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?