Skip to main content

IPA-123: Enums

By leveraging enumerations (enums) whenever a field only accepts a discrete set of values and documenting those values we can easily communicate to customers the expectation for that data field.

State

Adopt

Guidance​

  • API producers should use enumeration objects for sets of values for a field that are expected to remain relatively static
    • API producers may include additional documentation to include an explanation for each of the allowable fields
  • Enumeration values must be UPPER_SNAKE_CASE
  • API producers should default to having enums extensible to freely add more values
    • Enums must not be extended in a non-compatible fashion. I.e. splitting one enum value into two
  • API producers should use a string field if allowable enum values change often or exceed 20
    • If so, API producers must document the allowable values.

Example:

  • Stable Enum (small, rarely changes)
type: string
title: Alert Audit Types
description: Type of alert audit action.
enum:
  - ALERT_ACKNOWLEDGED_AUDIT
  - ALERT_UNACKNOWLEDGED_AUDIT
  • Dynamic or Large Enum Set (changing often or > 20 values)
type: string
title: Alert Audit Type
description: >
  String identifying the type of alert audit action. The list of allowed values
  changes frequently or is extensive (>20). Refer to the API documentation for
  the current list of allowed values.
example: ALERT_ACKNOWLEDGED_AUDIT
externalDocs:
  description: Current list of allowed values for Alert Audit Type
  url: link/to/docs/Alert+Audit+Types