String Literals for Enums - WunderGraph

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

The GraphQL specification distinguishes between enum literals and string literals in an operation document. An enum argument accepts the enum literal VALUE1, but not the string literal "VALUE1". By default, the router rejects a string literal used for an enum type with a validation error:

Enum "SomeEnum" cannot represent non-enum value: "VALUE1".

The allow_string_literals_for_enums option accepts such string literals when the string content matches one of the enum’s values. Strings that do not match a value are still rejected:

Value "NOPE" does not exist in "SomeEnum" enum.

This is a deviation from the GraphQL specification. Servers built on graphql-js reject string literals for enums. Prefer fixing clients to send enum literals. Use this option to keep existing clients working while they migrate.

Examples

Given the schema:

enum SomeEnum {
  VALUE1
  VALUE2
}

type Query {
  field(arg: SomeEnum): String
}

The following queries behave as listed:

{ field(arg: VALUE1) }    # Valid. Enum literal.
{ field(arg: "VALUE1") }  # Invalid by default. Valid with this option enabled.
{ field(arg: "NOPE") }    # Invalid. "NOPE" is not a value of SomeEnum.

Variables are not affected by this option. JSON has no enum type, so a string is the standard representation for an enum variable value and is always accepted when it matches an enum value:

query ($arg: SomeEnum) { field(arg: $arg) }
# variables: {"arg": "VALUE1"} is valid with or without this option

Configuration

ENGINE_ALLOW_STRING_LITERALS_FOR_ENUMS=true

config.yaml

version: "1"

engine:
  allow_string_literals_for_enums: true

This option is disabled by default. See the Router Configuration reference for all engine flags.