Complete directive support for sophisticated federation patterns

All Apollo Federation v1 and v2 directives, plus declarative authorization and subscription filtering. Directives are processed during composition and query planning, with authorization evaluated at the router before subgraph requests.

Declarative authorization without custom authorization code in every subgraph. Authorization directives require JWT provider configuration on the router.

@key @authenticated @requiresScopes @shareable @external @provides @extends @inaccessible @override @tag

Federation directives are declared in subgraph schemas, processed during composition and query planning, and used by the router to enforce authorization at request time.

The problem

Without full directive support, federation breaks down

Federated GraphQL architectures need a way to express entity relationships, field dependencies, cross-subgraph sharing, and access control. Without comprehensive directive support, teams build workarounds or get blocked entirely.

No directive support means workarounds everywhere

Without @key, @external, @requires, and @provides, teams cannot cleanly express entity relationships and field dependencies across subgraphs. The result is workaround logic or blocked federation patterns.

Authorization requires custom code in every subgraph

Without declarative auth directives, teams write custom authorization code in each subgraph, making access control harder to implement consistently.

Field sharing and subscription filtering have no standard

Without @shareable, teams cannot use the standard field-sharing pattern for fields resolved by multiple subgraphs. Without subscription filter support, teams lack directive-based event filtering for subscriptions.

Our solution

Full directive coverage, from entity resolution to authorization

Cosmo supports federation directives for core federation, field sharing, visibility control, authorization, and subscription filtering. Directives are processed across schema composition and query planning, with authorization directives evaluated at the router before subgraph requests.

How it all fits together

1. Core federation directives (@key, @external, @requires, @provides, @extends) express entity relationships and field dependencies across subgraphs.
2. @shareable enables multi-subgraph field resolution. @override supports migrating field ownership between subgraphs.
3. @authenticated and @requiresScopes enforce access control at the router level. Requests that fail the required authorization checks are rejected before protected subgraph requests are made.
4. @inaccessible hides fields from the client schema. @tag attaches metadata for contracts and tooling.
5. Cosmo-specific extensions include @openfed__subscriptionFilter, @openfed__configureDescription, and @semanticNonNull.

Directive validation happens during composition. Authorization checks are evaluated at the router before protected subgraph requests are made.

Federation directives

Before & After

Five directive groups

• Core federation — @key, @external, @requires, @provides, @extends
• Field sharing — @shareable, @override
• Visibility control — @inaccessible, @tag
• Authorization — @authenticated, @requiresScopes
• Cosmo extensions — @openfed__subscriptionFilter, @openfed__configureDescription, @semanticNonNull

Key benefits

Complete Federation directive support

Full Federation v1 and v2 directive support plus Cosmo-specific extensions.

Complete federation support

Cosmo supports all Apollo Federation v1 and v2 directives, including @key, @external, @requires, @provides, @extends, @shareable, @inaccessible, @override, @interfaceObject, and @tag.

Declarative authorization at the router

@authenticated and @requiresScopes enforce authorization at the router. Requests that fail the required authentication or scope checks are rejected before protected subgraph requests are made. Requires JWT provider configuration on the router.

Cross-subgraph field resolution

@shareable enables the same field to be resolved from multiple subgraphs. The query planner chooses the optimal subgraph based on the query plan.

Interface entity patterns

Interfaces can use @key(fields: "id"). Subgraphs that contribute fields to implementing types use @interfaceObject to add fields to all implementations.

Cosmo-specific extensions

@openfed__subscriptionFilter supports subscription event filtering. @openfed__configureDescription controls description propagation, and @semanticNonNull indicates semantic non-nullability.

How federation directives work

Declare directives in subgraph schemas

Each subgraph declares the directives it uses, such as @key for entity resolution, @authenticated for protected fields, and @shareable for shared fields. Authorization directives require JWT provider configuration on the router.

Composition validates directive usage

During schema composition, Cosmo validates directive usage across subgraphs so incompatible directive declarations can be caught before producing the composed schema.

Query planning uses field directives

Field-level directives such as @shareable, @provides, and @requires influence query planning decisions. @provides indicates conditionally available fields, and @requires declares field dependencies from other subgraphs.

Router evaluates authorization directives

@authenticated and @requiresScopes are evaluated at the router before protected subgraph requests are made. Requests that fail the required authentication or scope checks are rejected at the router.

Use cases

Common directive patterns

Declarative authentication

@authenticated

Fields or types annotated with @authenticated require valid authentication. The router validates authentication before protected subgraph requests are made. Unauthenticated requests receive authorization errors.

Scope-based authorization

@requiresScopes

Fields annotated with @requiresScopes(scopes: [["read:users"], ["admin"]]) require specific JWT scopes and support AND/OR logic. The router validates that the request JWT contains the required scopes before allowing access.

Cross-subgraph field resolution

@shareable

A field marked @shareable in all subgraphs that can resolve it can be resolved from multiple subgraphs. The query planner chooses the optimal subgraph based on the query plan.

Entity interface patterns

@interfaceObject

Interfaces can be declared with @key(fields: "id"). Subgraphs that contribute fields to implementing types use @interfaceObject to add fields to all implementations.

When to use federation directives

When to use

• You need entity resolution, field dependencies, or cross-subgraph field sharing in a federated graph.
• You want declarative authentication or scope-based authorization without custom authorization code in every subgraph.
• You are building subscription-based features and need @openfed__subscriptionFilter for event filtering.

Requirements & limitations

• Authorization directives (@authenticated and @requiresScopes) require JWT provider configuration on the router.
• Subscription filtering (@openfed__subscriptionFilter) requires an event-driven federation setup.

Build sophisticated federation patterns with directive support

Full v1 and v2 directive support, declarative authorization, and subscription filtering.