GQL Enums

GQLSchemaGen can generate GraphQL enum types from Go types and their constants. Enums can be string-based or integer-based (using iota). You annotate your Go type with @GqlEnum, and optionally provide a custom name and description.

String-based enums

Example:

user_roles.go

Generates:

schema.graphqls

Integer-based enums with iota

You can also define enums using iota:

permissions.go

Generates:

schema.graphqls

Auto-generated names

If you do not specify @GqlEnumValue(name:"..."), GQLSchemaGen generates enum value names automatically:

  • Strips the enum type prefix from the constant (e.g., UserRoleAdmin → Admin)
  • Converts the result to SCREAMING_SNAKE_CASE (Admin → ADMIN)

Example:

status.go

Generates:

schema.graphqls

Deprecated values

You can mark enum values as deprecated with the deprecated parameter:

order_status.go

Generates:

schema.graphqls

Cross-Package Enums

GQLSchemaGen fully supports enums where the type and its constants are defined in separate packages. This allows you to organize your project cleanly, keeping type definitions and constant values in different modules or files.

For example, you could define the enum type in one package:

types/status.go

And define the constants in another package:

constants/status_values.go

When you run gqlschemagen generate, the generated GraphQL enum will correctly include all constants regardless of which package they are declared in. This makes it easy to maintain large projects without coupling enum type definitions to their values.

Using enums in object types

Once an enum is defined, it can be used in @GqlType annotated structs just like any other type:

user.go

Directive Parameters

@GqlEnum

ParameterDescription
nameOptional custom GraphQL enum name. Defaults to the Go type name.
descriptionOptional description for the enum, used as a doc string.
namespaceOptional namespace for organizing schema files. Used with multiple files strategy.

@GqlEnumValue

ParameterDescription
nameOptional custom GraphQL enum value name. If omitted, name is auto-generated.
descriptionOptional description for the value.
deprecatedOptional deprecation reason, which will generate @deprecated(reason: "...").

Additional Notes

  • Enums must have at least one constant to generate.
  • Constant values must have explicit type annotations.
  • Enum types and constants can be defined in different files or packages. Cross-package enums are fully supported.
  • For integer-based enums, only the names are used in the schema; the numeric value is ignored.
  • GQLSchemaGen ensures Go ↔ GraphQL conversion automatically when using gqlgen directives.

Once your enums are annotated, run:

$ gqlschemagen generate

to include them in your GraphQL schema.

Next
Next: Field Filtering