import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Enumerations

:::important The information on this page is only applicable to Go, Python and TypeScript SDKs. Enumerations are not currently supported in the PHP SDK. :::

Dagger supports custom enumeration (enum) types, which can be used to restrict possible values for a string argument. Enum values are strictly validated, preventing common mistakes like accidentally passing null, true, or false.

:::note Following the GraphQL specification, enums are represented as strings in the Dagger API GraphQL schema and follow these rules:

Enum names cannot start with digits, and can only be composed of alphabets, digits or _.
Enum values are case-sensitive, and by convention should be upper-cased. :::

Here is an example of a Dagger Function that takes two arguments: an image reference and a severity filter. The latter is defined as an enum named Severity:

<Tabs groupId="language"> <TabItem value="Go"> ```go file=./snippets/enums/go/main.go ``` </TabItem> <TabItem value="Python"> ```python file=./snippets/enums/python/main.py ```

:::note dagger.Enum is a convenience base class for defining documentation, but you can also use enum.Enum directly. ::: </TabItem>

<TabItem value="TypeScript"> ```typescript file=./snippets/enums/typescript/index.ts ``` </TabItem> </Tabs>

Enumeration choices will be displayed when calling --help on a Dagger Function:

shell

dagger call scan --help

The result will be:

shell

USAGE
  dagger call scan [arguments]

ARGUMENTS
      --ref string                                  [required]
      --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL   [required]

Here's an example of calling the Dagger Function with an invalid enum argument:

shell

dagger call scan --ref=hello-world:latest --severity=FOO

This will result in an error that displays possible values, as follows:

shell

Error: invalid argument "FOO" for "--severity" flag: value should be one of UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL
Run 'dagger call scan --help' for usage.