Built-in directives

Use this guide when a query needs conditional or incremental execution, or when schema metadata must appear in introspection. Start with the supported built-ins before designing a custom directive system.

Introspection’s __schema.directives list is fixed to seven built-ins (exec/introspection.go). Executable directives are enforced while flattening selections; schema directives surface through reflection, schema.ScalarConfig, or exec.ParseSDL.

Supported directives (overview)Copy Anchor Link

Executable directivesCopy Anchor Link

@skip / @includeCopy Anchor Link

Evaluated automatically when exec merges selection sets (evalSkipInclude). Both require a Boolean if (literals or $variables).

{
  profile {
    id
    nickname @include(if: $withNick)
    oldHandle @skip(if: $production)
  }
}

@defer / @stream (incremental delivery)Copy Anchor Link

@defer delays fragment or spread selections behind the primary response. if: false removes the directive (work runs eagerly). label namespaces incremental patches.

@stream batches list output: the resolver must return Go slices or arrays. initialCount is how many list elements stay in the first data payload; the remainder ship as incremental[] parts. initialCount: 0 skips the eager prefix entirely - every element is scheduled as incremental work (see [completeListStreamed](https://github.com/grx-gql/grx/blob/main/exec/incremental.go)).

Multipart HTTP: set Accept: multipart/mixed so http calls Executor.ExecuteIncremental, wires an incremental collector, and emits @defer / @stream payloads over multipart/mixed (writeIncremental).

Fallback JSON (Execute): Without that Accept header - or inside tests invoking **Execute directly - the executor does not attach an incremental collector. @defer fragments flatten eagerly (collectDefers = false). @stream on lists is ignored, and the resolver’s slice is serialized in one completeValue / list pass exactly like ordinary GraphQL responses.

Regression-style coverage: incremental_delivery_test.go (**multipart round-trips against grx.NewServer).

Schema directives @deprecatedCopy Anchor Link

Output fields (code-first structs)Copy Anchor Link

Deprecation metadata uses gql tags, matching FIELD_DEFINITION on struct-backed GraphQL objects:

package graph

type Profile struct {
	ID         string `gql:"id,nonNull"`
	Username   string `gql:"username,nonNull"`
	LegacyName string `gql:"legacyName,deprecated=Use username instead"`
}

Introspection and GraphiQL read isDeprecated + deprecationReason. examples/directives/ bundles a runnable demo.

Executable examples in sandboxCopy Anchor Link

Combine struct-backed deprecation with client directives:

{
  me {
    id
    username @include(if: true)
    legacyName @skip(if: true)
  }
}

Schema directive @specifiedByCopy Anchor Link

Use schema.ScalarConfig.SpecifiedByURL when registering custom scalars, or SDL:

scalar DateTime @specifiedBy(url: "https://example.com/scalars/datetime")

Introspection exposes specifiedByURL.

Schema directive @oneOfCopy Anchor Link

Marks input objects so exactly one field may be supplied. grx honours inputType.IsOneOf during coercion (input_coercion.go).

Debugging & toolingCopy Anchor Link

RelatedCopy Anchor Link

• examples/directives
• Execution pipeline (validation + incremental notes)
• Define your schema (gql tag primer)