Customize Enums

Enum Value Naming

Basic Conversion

Enum values are named according to their values, with adjustments made to form valid identifiers:

Invalid characters are removed.
Values are converted to fit the case style of the target programming language.
Special characters (e.g., +, -, .) are converted to words like Plus, Minus, Dot.

Name Conflicts

If naming conflicts arise after sanitization deduplication is attempted by modifying case styles or adding suffixes.

For example given the following schema:


schema:
  type: string
  enum:
    - foo
    - Foo
    - FOO

Results in enum values FOO_LOWER, FOO_MIXED, FOO_UPPER.

If unique names cannot be resolved, a validation error will prompt you to resolve conflicts, potentially using the x-speakeasy-enums extension.


schema:
  type: integer
  enum:
    - 1
    - 2
    - 3
  x-speakeasy-enums:
    - NOT_STARTED
    - IN_PROGRESS
    - COMPLETE

Ensure the order in the enum array corresponds to the custom names in the x-speakeasy-enums array.

Enum Class Naming

Use the x-speakeasy-name-override attribute to customize enum class names:


  Enum:
      x-speakeasy-name-override: example_override
      type: string
      enum:
        - foo
        - FOO

Will produce:


class ExampleOverride(str, Enum):
    FOO_LOWER = 'foo'
    FOO_UPPER = 'FOO'

Name Conflict Considerations

Some cases (like open enums) may pose unique name resolutions challenges, particularly when similar names occur in the schema.

In name conflict cases the parent schema receives the original name, while the child schema's name is concatenated with the parent's name:


enum_field:
  oneOf:
    - type: string
    - type: string
      enum:
        - foo
        - FOO
      x-speakeasy-name-override: enum_field

Results in:


class EnumFieldEnumField(str, Enum):
  FOO_LOWER = 'value'
  FOO_UPPER = 'value'

To avoid naming conflicts, additional overrides may be necessary::


enum_field:
  x-speakeasy-name-override: enum_field_parent
          oneOf:
            - type: string
            - type: string
              enum:
                - foo
                - Foo
              x-speakeasy-name-override: enum_field

Which will result in:


class EnumField(str, Enum):
  FOO_LOWER = 'value'
  FOO_UPPER = 'value'