Linter rulesSwagger 2.0schema-enum-naming

schema-enum-naming

Since 0.9.0

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

Rule Details

Adhering to a consistent naming convention enhances the readability and maintainability of the API.

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 - THIS_IS_CONST_CASE
  • camel - thisIsCamelCase, also with acronyms (userID)
  • camel-strict - thisIsCamelCase, but no two capitals in a row (userId, not userID)
  • kebab - this-is-kebab-case
  • pascal - ThisIsPascalCase, also with acronyms (HTTPServer)
  • pascal-strict - ThisIsPascalCase, but no two capitals in a row (HttpServer, not HTTPServer)
  • header - This-Is-Header-Case
  • snake - this_is_snake_case

The default convention is const.

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]

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

When Not to Use It

If your API does not follow a specific naming convention for enum values, you may not need to use this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading