Federation Directives Reference

An index of directives supported by WunderGraph Cosmo.

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

Directive	Explanation
@authenticated	Marks a field or type as requiring authentication. Only requests with valid credentials can access it.
@composeDirective (planned)	Tells the composition process to preserve a specific custom type system directive in the supergraph.
@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__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.