ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-768] Extensible Enumerations ​

Principle ​

  • For open-ended enumerations, x-extensible-enum SHOULD be used instead of enum.
  • When using x-extensible-enum, it MUST be explicitly documented how it may be extended.
  • An initial set of values SHOULD be provided for x-extensible-enum, but it should not be considered complete or fixed.
  • Clients SHOULD be able to handle unknown enum values rather than failing when encountering an unknown value.
  • Each extensible enum value SHOULD provide the following:
    PropertyRequiredDefaultDescription
    valueYesn/aThe extensible enum value. Must conform to the specified type.
    descriptionYesn/aDescribes the semantic meaning of the value.
    deprecatedNofalseBoolean indicating the deprecation status of this enum value.

Description ​

Extensible enumerations allow API providers to add new enum values without breaking backward compatibility. This is particularly useful for APIs that need to evolve over time, avoiding version changes due to the addition of new values.

Example ​

Here's an example of an OpenAPI 3.1 specification using x-extensible-enum:

yaml
openapi: 3.1.0
info:
  title: Order API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: Get list of orders
      parameters:
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderStatus'
      responses:
        '200':
          description: Successfully retrieved order list
          content:
            application/json:    
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  schemas:
    OrderStatus:
      type: string
      x-extensible-enum:
        - value: PENDING
          description: Order waiting to be processed
        - value: PROCESSING
          description: Order being processed
        - value: COMPLETED
          description: Order completed
        - value: CANCELLED
          description: Order cancelled
        - value: REFUNDED
          description: Order refunded
        - value: ON_HOLD
          description: Order temporarily on hold
          deprecated: true
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/OrderStatus'
  • [ADP-24] Versioning Mechanism
  • [ADP-42] API Lifecycle Management
  • [ADP-702] Enumerable Value Conventions

References ​