Skip to content

[Fusion] Add Field Ownership and Sharing chapter #9350

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaelstaib merged 3 commits into from
Mar 10, 2026
Merged

[Fusion] Add Field Ownership and Sharing chapter #9350

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9714f33
[Fusion] Add Field Ownership and Sharing chapter
michaelstaib Mar 10, 2026
fda0d6b
edits
michaelstaib Mar 10, 2026
7899b5b
Merge branch 'main' into mst/fusion-docs-100326-2
michaelstaib Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions website/src/docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,11 @@
},
{
"path": "data-requirements-and-mapping",
"title": "Data Requirements and Mapping"
"title": "Data Requirements"
},
{
"path": "field-ownership-and-sharing",
"title": "Field Ownership and Sharing"
},
{
"path": "composition",
Expand All @@ -204,10 +208,6 @@
"path": "deployment-and-ci-cd",
"title": "Deployment and CI/CD"
},
{
"path": "nitro-cli-reference",
"title": "Nitro CLI Reference"
},
{
"path": "attribute-and-directive-reference",
"title": "Attribute and Directive Reference"
Expand Down
376 changes: 174 additions & 202 deletions website/src/docs/fusion/v16/adding-a-subgraph.md
View file
Open in desktop

Large diffs are not rendered by default.

44 changes: 22 additions & 22 deletions website/src/docs/fusion/v16/attribute-and-directive-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,28 @@ Quick reference for all Fusion-related attributes and their GraphQL directive eq

# Attribute and Directive Reference Table

| Attribute | Directive | Description | Guide Page |
| --------------------------- | --------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `[ObjectType<T>]` | — | Maps static class as extension to entity type T | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[QueryType]` | — | Marks class as contributing Query root fields | [Getting Started](/docs/fusion/v16/getting-started) |
| `[MutationType]` | — | Marks class as contributing Mutation root fields | [Getting Started](/docs/fusion/v16/getting-started) |
| `[SubscriptionType]` | — | Marks class as contributing Subscription root fields | [Getting Started](/docs/fusion/v16/getting-started) |
| `[Lookup]` | `@lookup` | Declares field as entity lookup resolver | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[NodeResolver]` | — | Marks as Relay node resolver | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Internal]` | `@internal` | Hides lookup from composed schema | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Shareable]` | `@shareable` | Allows multiple subgraphs to resolve field | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Parent(requires: "...")]` | — | Declares field requirements from parent | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Require("...")]` | `@require` | Declares complex field requirements | [Data Requirements and Mapping](/docs/fusion/v16/data-requirements-and-mapping), [Adding a Subgraph](/docs/fusion/v16/adding-a-subgraph) |
| `[EntityKey("...")]` | `@key` | Declares entity key for resolution | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[BindMember(nameof(...))]` | — | Replaces raw FK with resolved entity | [Adding a Subgraph](/docs/fusion/v16/adding-a-subgraph) |
| `[Tag("...")]` | `@tag` | Applies tag for composition filtering | [Composition](/docs/fusion/v16/composition) |
| `[DataLoader]` | — | Source-generates DataLoader interface | [Getting Started](/docs/fusion/v16/getting-started), [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[UsePaging]` | — | Enables cursor-based pagination | [Getting Started](/docs/fusion/v16/getting-started) |
| `[ID<T>]` | — | Declares field as Relay-style ID | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Inaccessible]` | `@inaccessible` | Hides from composite schema | [Composition](/docs/fusion/v16/composition) |
| `[Override(from: "...")]` | `@override` | Migrates field ownership | [Deployment and CI/CD](/docs/fusion/v16/deployment-and-ci-cd) |
| `[Provides("...")]` | `@provides` | Declares locally-resolvable subfields | [Data Requirements and Mapping](/docs/fusion/v16/data-requirements-and-mapping) |
| `[External]` | `@external` | Field defined by another subgraph | [Data Requirements and Mapping](/docs/fusion/v16/data-requirements-and-mapping) |
| Attribute | Directive | Description | Guide Page |
| --------------------------- | --------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `[ObjectType<T>]` | — | Maps static class as extension to entity type T | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[QueryType]` | — | Marks class as contributing Query root fields | [Getting Started](/docs/fusion/v16/getting-started) |
| `[MutationType]` | — | Marks class as contributing Mutation root fields | [Getting Started](/docs/fusion/v16/getting-started) |
| `[SubscriptionType]` | — | Marks class as contributing Subscription root fields | [Getting Started](/docs/fusion/v16/getting-started) |
| `[Lookup]` | `@lookup` | Declares field as entity lookup resolver | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[NodeResolver]` | — | Marks as Relay node resolver | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Internal]` | `@internal` | Hides lookup from composed schema | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Shareable]` | `@shareable` | Allows multiple subgraphs to resolve field | [Field Ownership and Sharing](/docs/fusion/v16/field-ownership-and-sharing) |
| `[Parent(requires: "...")]` | — | Declares field requirements from parent | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Require("...")]` | `@require` | Declares complex field requirements | [Data Requirements](/docs/fusion/v16/data-requirements-and-mapping), [Adding a Subgraph](/docs/fusion/v16/adding-a-subgraph) |
| `[EntityKey("...")]` | `@key` | Declares entity key for resolution | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[BindMember(nameof(...))]` | — | Replaces raw FK with resolved entity | [Adding a Subgraph](/docs/fusion/v16/adding-a-subgraph) |
| `[Tag("...")]` | `@tag` | Applies tag for composition filtering | [Composition](/docs/fusion/v16/composition) |
| `[DataLoader]` | — | Source-generates DataLoader interface | [Getting Started](/docs/fusion/v16/getting-started), [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[UsePaging]` | — | Enables cursor-based pagination | [Getting Started](/docs/fusion/v16/getting-started) |
| `[ID<T>]` | — | Declares field as Relay-style ID | [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) |
| `[Inaccessible]` | `@inaccessible` | Hides from composite schema | [Composition](/docs/fusion/v16/composition) |
| `[Override(from: "...")]` | `@override` | Migrates field ownership | [Deployment and CI/CD](/docs/fusion/v16/deployment-and-ci-cd) |
| `[Provides("...")]` | `@provides` | Declares locally-resolvable subfields | [Field Ownership and Sharing](/docs/fusion/v16/field-ownership-and-sharing), [Data Requirements](/docs/fusion/v16/data-requirements-and-mapping) |
| `[External]` | `@external` | Field defined by another subgraph | [Field Ownership and Sharing](/docs/fusion/v16/field-ownership-and-sharing), [Data Requirements](/docs/fusion/v16/data-requirements-and-mapping) |

# See Also

Expand Down
2 changes: 1 addition & 1 deletion website/src/docs/fusion/v16/authentication-and-authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,7 @@ Key details:
- The JWT configuration can mirror the gateway's configuration, or the subgraph can validate the forwarded `Authorization` header against the same identity provider.
- Subgraphs receive the raw `Authorization` header from the gateway via header propagation, so the JWT middleware validates the same token the gateway already validated.

### Using `[Authorize]` on Fields
### Field-Level Authorization

Apply `[Authorize]` to restrict access to specific fields or types:

Expand Down
14 changes: 7 additions & 7 deletions website/src/docs/fusion/v16/composition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ Why? If one subgraph requires a non-nullable argument, the gateway must always p

Not everything in your subgraph schemas should appear in the composite schema. Fusion provides three mechanisms for controlling what clients see.

### `@inaccessible` / `[Inaccessible]`
### Hiding Fields from the Composite Schema

Hides a type or field from the client-facing composite schema. The element still exists in the execution schema and can be used internally -- for example, as a source for `[Require]` field dependencies.

Expand Down Expand Up @@ -207,7 +207,7 @@ type Product @key(fields: "id") {

**Constraints:** You cannot mark a required input field as `@inaccessible` -- if a client must provide a value, they need to see the field. Composition fails if you try.

### `@internal` / `[Internal]`
### Subgraph-Local Elements

Declares that a type or field is local to a subgraph and does not participate in standard schema merging. Internal elements do not appear in the composite schema and do not collide with identically-named elements in other subgraphs.

Expand All @@ -228,7 +228,7 @@ This lookup is available to the gateway for resolving `Product` entity reference

The difference from `@inaccessible`: internal elements are completely invisible to the merging process. Two subgraphs can define `[Internal]` fields with the same name and different types without causing a conflict. `@inaccessible` elements still participate in merging -- they just get removed from the final client-facing schema.

### `[Tag]` for Composition Filtering
### Composition Filtering with Tags

Tags allow you to label fields and types for organizational purposes and selectively exclude them during composition using the `--exclude-tag` flag.

Expand Down Expand Up @@ -267,7 +267,7 @@ The `GetRecommendations` field is excluded from the composed schema. This is use
- Creating different compositions for different environments (dev includes experimental features, production does not).
- Organizing fields by team ownership for filtering.

## The `.far` Archive Format
## The Fusion Archive Format

The Fusion archive (`.far` file) is the output of composition and the input to the gateway. It is a binary package containing:

Expand Down Expand Up @@ -403,7 +403,7 @@ You can also run composition in Nitro cloud as part of your schema delivery pipe

These are the errors you will encounter most often, with examples showing what went wrong and how to fix it.

### Field Defined in Multiple Subgraphs Without `[Shareable]`
### Field Defined in Multiple Subgraphs Without Sharing

**Error:** `Field "Product.name" is defined in multiple subgraphs without @shareable.`

Expand Down Expand Up @@ -537,7 +537,7 @@ After merging, the `Purchasable` interface has both `price` and `refundPolicy`.

**Fix:** Add the missing field to the implementing type in the appropriate subgraph, or mark the new interface field as `@inaccessible` if it should not be in the composite schema.

### Required Input Field Marked `@inaccessible`
### Required Input Field Hidden from Composite Schema

**Error:** `Required input field "CreateProductInput.name" is marked @inaccessible. Required input fields cannot be hidden from the composite schema.`

Expand All @@ -561,7 +561,7 @@ Products/

If you renamed files, make sure the names match. Run `dotnet run -- schema export` to regenerate both files.

## `schema-settings.json` Reference
## Schema Settings Reference

Each subgraph's `schema-settings.json` configures how the subgraph participates in composition. The primary documentation lives on the [Adding a Subgraph](/docs/fusion/v16/adding-a-subgraph) page. Here is a quick reference of the fields relevant to composition:

Expand Down
10 changes: 5 additions & 5 deletions website/src/docs/fusion/v16/data-requirements-and-mapping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Data Requirements and Mapping"
title: "Data Requirements"
---

In traditional distributed systems, dependencies between services hide beneath the surface. A service assumes another service provides certain fields, responds in a certain shape, or is available at a certain time. These assumptions are invisible: they live in code, not in contracts. You discover them when something breaks in production. A field gets renamed, a service changes its response format, or a new team removes data another team depended on without knowing.
Expand Down Expand Up @@ -235,11 +235,11 @@ type Product {

The path `seller.addresses[countryCode]` means: navigate to `seller.addresses` (a list), then select `countryCode` from each element. If the seller has three addresses with country codes `"US"`, `"DE"`, and `"US"`, the resolver receives `["US", "DE", "US"]` as the `countryCodes` argument.

## `@provides`: Declaring Contextually Available Fields
## Declaring Contextually Available Fields

Use `@provides` on a field that returns an entity to tell the gateway that certain subfields of that entity are available when resolved through this specific field. The subgraph does not own those fields globally, but it can provide them in this context.

### When `@provides` Helps
### When Contextual Availability Helps

Consider a Reviews subgraph where the `author` field returns a `User` entity. The `User` type and its `username` field are owned by the Accounts subgraph. Normally the gateway would need to call the Accounts subgraph to fetch `username`. But the Reviews subgraph already has the author's username available when resolving `Review.author`. By annotating the `author` field with `@provides(fields: "username")`, the subgraph tells the gateway: "When you resolve `author` through the `Review` entity on my subgraph, I can also give you `username`."

Expand Down Expand Up @@ -298,7 +298,7 @@ type Review {
}
```

### When to Use `@provides`
### When to Provide Fields Contextually

Use `@provides` when:

Expand Down Expand Up @@ -389,5 +389,5 @@ If a `@require` argument appears in the composite schema when it should not, che
## Next Steps

- **Need entity identity and lookup patterns?** See [Entities and Lookups](/docs/fusion/v16/entities-and-lookups) for the full guide to keys, public vs. internal lookups, and composite keys.
- **Need field ownership and merging rules?** See [Composition](/docs/fusion/v16/composition) for how `@shareable`, `@inaccessible`, and composition validation work.
- **Need field ownership contracts and sharing semantics?** See [Field Ownership and Sharing](/docs/fusion/v16/field-ownership-and-sharing).
- **Need the directive and attribute quick reference?** See the [Attribute and Directive Reference](/docs/fusion/v16/attribute-and-directive-reference).
4 changes: 2 additions & 2 deletions website/src/docs/fusion/v16/deployment-and-ci-cd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -494,7 +494,7 @@ builder.Services

# Schema Evolution

## Progressive Field Migration with `[Override]`
## Progressive Field Migration

Use `[Override]` to migrate a field from one subgraph to another without breaking existing queries.

Expand Down Expand Up @@ -534,7 +534,7 @@ public static partial class ProductNode

The `[Override]` attribute tells the gateway: "This field used to be resolved by the `products-api` subgraph, but now this subgraph resolves it." The gateway routes queries to the new resolver, and the old resolver is no longer called.

## Excluding Experimental Features with `[Tag]`
## Excluding Experimental Features with Tags

Mark fields or types with `[Tag]` to exclude them from composition during development:

Expand Down
Loading