[ADP-702] Enumeration Value Conventions

Guidelines

• MUST use UPPER_SNAKE_CASE to represent enumeration values, unless in specific cases where the enumeration value is commonly used in lowercase in the industry, exceptions can be made.
• SHOULD use string-based enumerations rather than numeric ones.
  • Exception: When the enumeration value is a version number like 1.0.
• SHOULD provide clear, self-explanatory, consistent and descriptive names for each enumeration value.
  • SHOULD NOT use non-widely recognized abbreviations.
  • Ideally, the meaning of each enum value should be self-evident, so the API user does not need to consult documentation.
• MAY provide descriptions for each enumeration value in API documentation.
• SHOULD use extensible enumerations where possible..
• When deprecating an enumeration value, it SHOULD be marked as deprecated in the documentation.
• The entire document SHOULD use the same enumeration value design to describe specific data.

Design Considerations

Although the naming of the "type" field often appears to be enumerative, for problem+json, it must be a URI reference. For compatibility requirements, see [ADP-401] HTTP Problem Basics.

Enumeration values should remain consistent throughout the API to enhance readability and maintainability. Using UPPER_SNAKE_CASE provides clear visual distinction for enumeration values and aligns with common programming conventions.

String-based enumerations are preferred over numeric ones because they are self-documenting and less error-prone. They also provide better readability in API responses and documentation.

Examples

Correct Approach:

{
  "role": "GROUP_ADMINISTRATOR",
  "status": "ACTIVE",
  "permission": "READ_WRITE"
}

DON'T:

{
  "role": "groupAdministrator",
  "status": "active",
  "permission": "readWrite"
}

SHOULDN'T:

{
   "role": 1,
   "status": 2,
   "permission": 3
}

• If the value is not used for computation later, always return string-based enumeration.

OpenAPI Example

openapi: 3.0.0
info:
  title: Role API
  version: 1.0.0
paths:
  /roles:
    get:
      summary: Get roles
      responses:
        '200':
          description: A list of roles
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    role:
                      type: string
                      enum:
                        - GROUP_ADMINISTRATOR
                        - USER
                        - MODERATOR
                      example: GROUP_ADMINISTRATOR
                    status:
                      type: string
                      enum:
                        - ACTIVE
                        - INACTIVE
                        - SUSPENDED
                      example: ACTIVE
    post:
      summary: Create a role
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                    - GROUP_ADMINISTRATOR
                    - USER
                    - MODERATOR
                  example: GROUP_ADMINISTRATOR
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                  example: ACTIVE
      responses:
        '201':
          description: Role created

Related ADPs

• [ADP-401] HTTP Problem Basics
• [ADP-42] API Lifecycle Management
• [ADP-701] Property Design

References

• https://api.otto.de/portal/guidelines/r004090
• https://opensource.zalando.com/restful-api-guidelines/#240
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

Changelog

• 2024.11.11: Add self-explanatory to enum value.