schema-property-naming (Swagger 2.0 linter rule)

schema-property-naming

Since 0.9.0

This rule ensures that the names of schema properties adhere to a predefined naming convention.

Rule Details

Adhering to a consistent naming convention enhances the readability and maintainability of the API, and makes payloads easier to map to native data structures.

The schema-property-naming rule checks the keys of the properties map of every schema of a Swagger 2.0 document (schemas with a $ref are checked where they are defined). For every property whose name is not in the expected convention, it reports Schema property '<name>' is not in the '<convention>' convention, where <convention> is the display name of the convention (e.g. snake_case). The issue is reported at the schema that declares the property.

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 snake.

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-property-naming: [error, camel]

Examples

Good. With the default configuration.

swagger: '2.0'
info:
  title: Users
  version: 1.0.0
paths: {}
definitions:
  User:
    type: object
    properties:
      first_name:
        type: string
      last_name:
        type: string

Bad. With the default configuration.

swagger: '2.0'
info:
  title: Users
  version: 1.0.0
paths: {}
definitions:
  User:
    type: object
    properties:
      firstName:
        type: string
      LastName:
        type: string

When Not to Use It

If your API does not follow a specific naming convention for property names, 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.