GraphQL / Advanced: bounded and distributed execution / Lesson 16

Federation, composition and service boundaries

Evaluate a composed graph as a distributed system with explicit entity ownership and failure boundaries.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Separate language specification, composition dialect and gateway behavior.
Trace cross-service identity, permission and query-plan fanout.

Federate only when ownership justifies the cost

A federated graph composes capabilities owned by multiple services behind a unified client contract. It can support independent domain ownership, but it also introduces composition rules, query planning, network hops and coordinated release concerns. It is not required merely because the schema is large. A modular single service may provide clearer boundaries with less operational overhead. State which teams own Course, Author and Enrollment semantics, how changes are reviewed and which service is authoritative for each field before choosing a federation product or syntax.

Describe field ownership without inventing a standard dialect

Federation implementations use specific directive dialects and entity protocols that are not interchangeable simply because they expose GraphQL. The JSON manifest below is a local architecture note, not SDL accepted by any gateway. It separates identity ownership from a field supplied by another domain. A course key exchanged between services must have stable scope and representation, and its possession must not imply permission to read enrollment information. Verify the exact federation implementation, version and composition rules before translating this design into configuration.

json Synthetic entity ownership note

{
  "entity": "Course",
  "identityOwner": "catalog",
  "keyScope": ["tenantId", "courseId"],
  "fields": {"title": "catalog", "eligibleEnrollmentCount": "enrollment"},
  "authorization": "enforced-by-owning-domain"
}

The manifest records responsibility and scope. It does not define a gateway protocol or grant enrollment access.

Propagate trusted identity with least authority

A gateway often passes request context to downstream services, but blindly forwarding arbitrary client headers is unsafe. Each service needs an authenticated service-to-service trust boundary and a verified representation of the end-user scope it is allowed to act on. Domain authorization should remain enforceable at the owning service rather than depending exclusively on a gateway filter. Avoid exposing internal entity lookup entry points to untrusted callers without equivalent policy. Review whether errors, caches and traces preserve tenant boundaries when several services participate in one operation.

Trace a query plan as a dependency graph

Assume catalog first returns eligible course keys and titles, then enrollment resolves a count for those keys. These stages can form a dependency chain even though sibling field execution appears parallel in a client document. Batch entity lookups to avoid one network call per course, but keep source limits. The record below is an illustrative plan explanation, not output from an actual planner. Composition success confirms structural rules under a particular tool; it does not prove that the deployed services are reachable, authorized or fast enough for the operation.

json Illustrative cross-service plan

{
  "operation": "CourseEnrollmentCards",
  "steps": [
    {"service": "catalog", "returns": ["courseKeys", "title"]},
    {"service": "enrollment", "dependsOn": "courseKeys", "mode": "bounded-batch", "returns": ["eligibleEnrollmentCount"]}
  ]
}

The enrollment step depends on catalog keys. A shared deadline must account for the whole chain rather than giving every hop an unlimited fresh timeout.

Coordinate composition, deployment and rollback evidence

Validate subgraph changes against the intended composed schema and supported operations before deployment. A gateway may understand a new field while an older service instance does not, so rolling release compatibility matters. Keep query-plan observations, partial-failure semantics and rollback artifacts in review. If enrollment fails, a nullable count can preserve the course card; a non-null promise may propagate the failure more widely. Federation should retain clear domain failure boundaries instead of making one optional remote feature a mandatory dependency for every otherwise local read.

Common errors and fixes

A course key grants access to private counts

Why it happens: Cross-service identity was mistaken for authorization.
How to fix it: Enforce end-user scope in the owning enrollment domain.
Prevent it next time: Test entity lookups under denied principals.

Composition passes but requests fail during rollout

Why it happens: Deployed service versions do not match the planned contract.
How to fix it: Restore overlap and deploy compatible schema/service artifacts.
Prevent it next time: Validate rolling and rollback combinations.

One card list makes many remote calls

Why it happens: Entity hydration was not batched or bounded.
How to fix it: Inspect the plan and use supported bounded entity batching.
Prevent it next time: Track remote call count and chain duration by operation.

Check your understanding

1. Why is federation not simply merging SDL files?

Show worked solution

The system must agree on entity identity, field ownership, composition compatibility, query planning, trust propagation and deployment behavior. A combined schema text does not implement these protocols or resolve distributed failures. Choose a documented implementation and verify both its composition artifact and the actual bounded service plan for supported operations.

2. How should an optional remote enrollment count affect nullability?