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(alsoUPPER_CASEandSCREAMING_SNAKE_CASE) - THIS_IS_CONST_CASEcamelCase- thisIsCamelCase, also with acronyms (userID)camelCaseStrict- thisIsCamelCase, but no two capitals in a row (userId, not userID)kebab-case- this-is-kebab-casePascalCase- ThisIsPascalCase, also with acronyms (HTTPServer)PascalCaseStrict- ThisIsPascalCase, but no two capitals in a row (HttpServer, not HTTPServer)Header-Case- This-Is-Header-Casesnake_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