Directives Reference - WunderGraph

GraphQL Directives

This page lists the GraphQL directives currently supported by WunderGraph Cosmo. Each entry includes a brief description. For usage details, see the directive’s documentation or related federation guides.

GraphQL Specification

Directive Explanation
@deprecated Marks fields, arguments, input fields, and enum values as deprecated. The optional reason argument describes what to use instead. Deprecated elements remain functional; the directive is a documentation and tooling signal exposed through introspection.
@oneOf This built-in directive is used within the type system definition language to indicate an Input Object is a OneOf Input Object. See specification for details. Requires router 0.259.0 and wgc 0.93.3.
@semanticNonNull Indicates that a position is semantically non null: it is only null if there is a matching error in the errors array. In all other cases, the position is non-null. Requires wgc 0.93.1.
@specifiedBy Links a custom scalar type to a human-readable specification URL describing its format, serialization, and coercion rules. The URL is exposed through introspection via the specifiedByURL field. Must not be applied to built-in scalars.

Federation

Directive Explanation
@authenticated Marks a field or type as requiring authentication. Only requests with valid credentials can access it.
@composeDirective Tells the composition process to preserve a specific custom type system directive in the supergraph.
@connect__fieldResolver Marks a field so the router resolves it through a separate gRPC RPC call. The context argument specifies which parent fields to pass. Part of the Cosmo Connect gRPC integration. See Field Resolvers for the full guide.
@edfs__kafkaPublish Marks a mutation field that publishes an event to a Kafka topic. Requires a topic and provider ID.
@edfs__kafkaSubscribe Declares a subscription field that listens to one or more Kafka topics. Used in EDG Subscription fields.
@edfs__natsPublish Marks a mutation field that publishes an event to a NATS subject. Requires a subject and provider ID.
@edfs__natsRequest Declares a query field that requests an event over NATS and expects a response. Used in EDG Query fields.
@edfs__natsSubscribe Marks a subscription field that listens to one or more NATS subjects. Can include stream configuration.
@external Marks a field as coming from another subgraph in a federated GraphQL schema. The field exists on the base type in a different subgraph and is not resolved by the current one, but it can be referenced if needed by directives or to satisfy an interface. In addition to indicating data ownership, @external is used in several advanced scenarios: to satisfy an interface implementation, to reference a field that may be conditionally provided via @provides, or to declare a dependency used by @requires.
@extends Marks an object or interface as an extension of a type that is defined in another subgraph, typically when the subgraph’s GraphQL implementation does not support the extend keyword. This directive is mainly used by subgraph servers that lack native support for type extensions. In Federation v2, this is no longer required to mark entity types as extensions. Any subgraph can contribute fields to an entity without declaring it as an extension. In Federation v1, each entity had an originating subgraph, and any other subgraph referencing that entity was required to use the extend keyword. The @extends directive remains in use primarily for backward compatibility and edge cases in tooling support.
@inaccessible Hides a field or type from the client schema. It cannot be queried by the user, but the planner may still access it if used in a @key, @requires, or @provides directive. Types marked as inaccessible are excluded from unions and interfaces. If the server returns one, the router will either return an error or render the object as null depending on the field’s nullability.
@interfaceObject Used to mark a type that corresponds to an interface in another subgraph, where that interface has a @key directive. This kind of interface is referred to as an entity interface. The directive allows the subgraph to contribute fields to every type that implements the entity interface in the other subgraph. When using @interfaceObject, the same subgraph must not define any of the implementing types, or it will result in a composition error.
@key Declares one or more fields that uniquely identify an entity across subgraphs. It has two arguments. The fields argument is of type fieldSet, which represents a GraphQL selection set with omitted curly braces {}. The resolvable argument defaults to true. If resolvable is set to false, the subgraph will not be used to resolve fields for that entity, because it does not implement the entity reference resolver for the given key. The only exception is when one of the fields uses the @requires directive, and in that case, the planner may still route a query to the subgraph, but only the field resolver will run, not the entity reference resolver.
@link Used to reference an external specification and optionally import types or directives into a subgraph schema. For Cosmo, this directive is ignored and removed during composition.
@openfed__configureDescription Allows controlling how and whether descriptions are propagated to the federated schema. Supports overrides, hiding, and composition on extensions.
@openfed__requireFetchReasons Enables fetch reason propagation to subgraph requests for annotated fields. The router adds a fetch_reasons extension describing why each field is being fetched (by user, by subgraph dependency, as a key, or to satisfy @requires). Requires enable_require_fetch_reasons: true in router config.
@openfed__subscriptionFilter Applies a filter condition to a subscription field, restricting events based on field values or logical expressions.
@override Specifies that a field now resolves from the current subgraph instead of the one that previously defined it.
@provides Indicates that specific fields can be resolved from this subgraph, but only on the schema path where the directive is applied. The fields listed in the fields argument must be marked as @external. If a parent field of a nested external field is marked as @external, and there are sibling fields that are not external, those sibling fields will also be available for resolution on the parent external path.
@requires Declares that a field’s resolver depends on other fields that must be fetched from another subgraph before it can be resolved. The fields argument is of type fieldSet. Required fields are not fetched until the necessary data is retrieved from the other subgraph. These fields are then passed along with key values in the representation variables.
@requiresScopes Restricts access to schema elements based on JWT scopes, enabling fine-grained authorization policies.
@shareable Marks a field or type as safe to define in multiple subgraphs. This means the field can be resolved from more than one subgraph, and the query planner decides which one to use. If all options are equal, the planner will choose the first subgraph based on their order of appearance. If the shared field is a root query field and its return type defines different fields across subgraphs, both fields will be queried and merged. However, this pattern is discouraged because subgraphs are then responsible for maintaining data integrity. In general, shareable fields are expected to return the same value regardless of which subgraph resolves them. Key fields are shareable by default.
@tag Attaches custom metadata to schema elements, often used by tooling such as contracts, filters, or analysis workflows. The directive takes a single argument: the tag name.