boolean-parameter-prefixes

Enforces specific and consistent naming for request parameters with boolean type. When this rule is enabled, the name fields of all boolean parameters in your API must contain one of the configured prefixes.

OAS Compatibility
2.0 ✅
3.0 ✅
3.1 ✅
components
enforces names for boolean types
NamedParameter
root
Paths
PathItem
Operation
Parameter
Schema

API design principles

Consistency in API design makes APIs easier to use. Being able to identity boolean types from their names is possible when they use consistent prefixes, such as is or has. If you saw an API with these parameters, you could identify the boolean parameters by their names:

  • orderNumber
  • amount
  • hasPaid
  • shippingService
  • isFulfilled
  • customerReference

The nuance of being able to identify the boolean parameters helps developers produce and consume APIs.

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default off.
prefixes [string] List of allowed boolean parameter prefixes. Default values are is and has.

An example configuration:

Copy
Copied
rules:
  boolean-parameter-prefixes: error

The following example configures prefixes:

Copy
Copied
rules:
  boolean-parameter-prefixes:
    severity: error
    prefixes: ["can", "is", "has"]

Examples

Given the configuration with the prefixes can, is, and has, the following example shows an error.

Example of incorrect boolean parameter prefixes:

Copy
Copied
schema:
  type: object
  properties:
    belongsToUser:
      type: boolean
      default: false

Example of correct boolean parameter prefixes:

Copy
Copied
schema:
  type: object
  properties:
    isUser:
      type: boolean
      default: false

Related rules

Resources