Schema Composition and Domain Boundaries

Owning a Slice of One Graph

A single schema with forty contributing teams fails in a predictable way: two teams define search, three define Error, and every pull request touches files nobody owns. The fix is not splitting into separate services the client must stitch together — it is organizing one graph so each team owns a section and can change it without negotiating with everyone.

src/
  shared/
    scalars.graphql      # DateTime, JSON, Money
    page.graphql         # Page, PageInfo, cursor pagination
  domains/
    catalog/
      schema.graphql     # Product, Category, Query.product, Query.products
      resolvers.ts
    billing/
      schema.graphql     # Invoice, Transaction, Query.invoice
      resolvers.ts
    shipping/
      schema.graphql     # Shipment, Query.shipment
      resolvers.ts

Two rules make the layout work:

• Root fields are namespaced by domain vocabulary. product(id:), invoice(id:), shipment(id:) — no bare search or get fields two teams can both claim. A collision is then a merge conflict in review instead of a gateway that refuses to start.
• Ownership follows the directory. CODEOWNERS maps domains/billing/** to the billing team, so a schema change is reviewed by people who understand its consumers and the rest of the graph stays out of the diff.

Types get namespaced the same way when a word is ambiguous: ShippingAddress and BillingAddress beat two teams each defining Address with different fields. If two domains genuinely mean the same thing, that is a signal to move the type to shared/ rather than let each one keep a private copy.

The client still sees one endpoint with one introspection result. Composition happens at build or publish time on the server side; nobody hands a client three schemas and asks them to merge — see stitching versus federation for how that server-side assembly is structured.

Shared Types and Explicit Cross-Domain Fields

Some types belong to nobody because everybody needs them: Money, PageInfo, DateTime, a shared Actor. Define them once in shared/ and import them everywhere. Two modules each defining their own Money is a composition failure waiting to happen — in federation it is an outright compose error, and in plain builds it is two types that look identical and normalize differently in a client cache.

Cross-domain references deserve the same discipline. The tempting shortcut:

# billing/schema.graphql
type Invoice {
  id: ID!
  total: Money!
  "Reaches into the catalog database. No field owner, no resolver boundary."
  productSku: String!
}

The explicit version:

type Invoice {
  id: ID!
  total: Money!
  lines: [InvoiceLine!]!   # billing owns these
}

type InvoiceLine {
  description: String!
  amount: Money!
  product: Product!        # cross-domain field with a named resolver
}

InvoiceLine.product is a real field whose resolver is written by billing and calls the catalog's public API or loader. The dependency is visible in code review, instrumentable with its own latency metrics, and removable when the integration goes away. A hidden join reaching across databases produces none of those: a catalog migration silently breaks billing queries, and nobody discovers the coupling until an incident has two teams in the same room.

The trade you are making

An explicit field can cost an extra hop in the query plan. That cost is a known, solvable problem — batching across the boundary keeps it to one request per parent set, as in manual batch loading — while invisible coupling has no ceiling and no owner. Prefer the explicit field, and let the resolver decide whether the data comes from a join, a cache, or a service call; the schema should describe the shape of the graph, not the topology of the databases behind it.

Circular references between domains are acceptable in GraphQL — depth and cost limits are what protect you — provided each crossing edge is a declared field with an owner rather than an accident of two teams pointing at each other's tables.

Composition Checks Before Merge

Composition is where naming collisions, redefinitions, and accidental breakage surface. Catch them in CI, where the failure is a red build instead of a gateway that will not start at 2 a.m.

# plain schema diff: fails on breaking changes
npx @graphql-inspector/diff current.graphql proposed.graphql

# federation: validate the subgraph against the registered supergraph
rover subgraph check my-graph@prod --name catalog --schema ./schema.graphql

What these catch that human review often misses:

The directive row surprises people: two teams writing the same directive definition with a different argument list is not merged, it is rejected — the composition engine has no basis for choosing a winner. Moving shared directives to shared/ alongside shared types removes the whole class, which is the theme of this topic: duplicates are cheaper to prevent than to resolve.

The review checklist

1. Names are owned. Every type and root field maps to one directory and one team.
2. Shared types are imported, never redefined. Money exists once, in shared/.
3. Cross-domain fields name their resolver. No field that only works if someone else's table shape holds.
4. Directive definitions appear once, in the shared module — see custom type system directives.
5. Breaking changes have a runway. A diff that removes a field goes back for a plan — see deprecation strategy.

Why this is worth ceremony

Teams ship independently only while the graph enforces the boundaries for them. With owned modules, imported shared types, explicit crossing fields, and a mechanical check on every pull request, a schema grows the way a well-structured codebase does: bounded pieces, visible dependencies, and failures that happen where the fix is cheap.