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.

DirectiveExplanation
@authenticatedMarks 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__kafkaPublishMarks a mutation field that publishes an event to a Kafka topic. Requires a topic and provider ID.
@edfs__kafkaSubscribeDeclares a subscription field that listens to one or more Kafka topics. Used in EDG Subscription fields.
@edfs__natsPublishMarks a mutation field that publishes an event to a NATS subject. Requires a subject and provider ID.
@edfs__natsRequestDeclares a query field that requests an event over NATS and expects a response. Used in EDG Query fields.
@edfs__natsSubscribeMarks a subscription field that listens to one or more NATS subjects. Can include stream configuration.
@externalMarks 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.
@extendsMarks 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.
@inaccessibleHides 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.
@interfaceObjectUsed 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.
@keyDeclares 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.
@linkUsed 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__configureDescriptionAllows controlling how and whether descriptions are propagated to the federated schema. Supports overrides, hiding, and composition on extensions.
@openfed__subscriptionFilterApplies a filter condition to a subscription field, restricting events based on field values or logical expressions.
@overrideSpecifies that a field now resolves from the current subgraph instead of the one that previously defined it.
@providesIndicates 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.
@requiresDeclares 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.
@requiresScopesRestricts access to schema elements based on JWT scopes, enabling fine-grained authorization policies.
@shareableMarks 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.
@tagAttaches 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.