docs: add documentation for missing directives#2722
Merged
Conversation
…dResolver, and @openfed__requireFetchReasons directives Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
WalkthroughDocumentation pages for four new GraphQL federation directives ( Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (5)
docs-website/federation/directives/specifiedby.mdx (2)
56-59: Document the composition behavior when URLs differ.Line 57 states that "every subgraph that defines the same custom scalar should use the same
@specifiedByURL," but doesn't explain what happens if they differ. Based on relevant code snippets, the composition uses a last-one-wins strategy when URLs differ.Consider documenting the actual behavior to set correct expectations.
📝 Suggested addition
In a federated graph, every subgraph that defines the same custom scalar should use the same `@specifiedBy` URL. +If subgraphs provide different URLs for the same scalar, +composition preserves the last URL encountered without raising an error. Cosmo preserves the directive through composition so that introspection on the federated schema returns the `specifiedByURL` for each annotated scalar.Based on relevant code snippets from
composition/src/buildASTSchema/extendSchema.ts:375-388, which shows the last-one-wins merge strategy.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/federation/directives/specifiedby.mdx` around lines 56 - 59, Update the specifiedby.mdx text to document the composition behavior when subgraphs provide different `@specifiedBy` URLs: explain that during composition the implementation follows a "last-one-wins" merge strategy (as implemented in extendSchema/extendSchema.ts), so the URL from the last-applied subgraph will be preserved in the composed schema's specifiedByURL; mention this explicitly alongside the existing guidance that subgraphs should use the same URL to avoid surprises.
23-26: Consider splitting the long sentence.Lines 23-26 contain a sentence with multiple comma-separated clauses. As per coding guidelines, prefer short, declarative sentences.
✏️ Suggested split
-It provides a machine-readable link between a custom scalar type and the document -that describes its serialization, -coercion, -and validation rules. +It links a custom scalar type to a document describing its format. +The document specifies serialization, coercion, and validation rules.As per coding guidelines, prefer short, declarative sentences when a sentence has more than one comma-separated clause.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/federation/directives/specifiedby.mdx` around lines 23 - 26, The long sentence "It provides a machine-readable link between a custom scalar type and the document that describes its serialization, coercion, and validation rules." should be split into shorter declarative sentences; edit the text so the first sentence states that it provides a machine-readable link between a custom scalar type and the document that describes its serialization, and follow with one or two short sentences that state the document also describes coercion and validation rules (e.g., split into "It provides a machine-readable link between a custom scalar type and the document that describes its serialization. The document also describes coercion and validation rules.").docs-website/federation/directives/openfed__requirefetchreasons.mdx (2)
2-2: Title formatting inconsistency with directive name.The title shows "@openfed requireFetchReasons" with a space, but the actual directive name is
@openfed__requireFetchReasonswith double underscores. Consider using the exact directive name for consistency with other directive documentation pages.📝 Suggested correction
-title: "@openfed requireFetchReasons" +title: "@openfed__requireFetchReasons"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/federation/directives/openfed__requirefetchreasons.mdx` at line 2, Update the page title to match the actual directive name: replace the current title string "@openfed requireFetchReasons" with the exact directive identifier "@openfed__requireFetchReasons" so the header matches the directive symbol used elsewhere (referencing the directive name `@openfed__requireFetchReasons`).
29-44: Consider tightening the compliance use-case explanation.Lines 29-44 contain multiple long sentences with several comma-separated clauses explaining the compliance scenario. As per coding guidelines, prefer short, declarative sentences and avoid over-explanation.
✏️ Suggested refinement
-This is particularly useful for compliance-sensitive data. In a federated graph, -any subgraph can use `@requires` to declare a dependency on a field from another subgraph. -When that happens, -the router fetches the field automatically — no explicit permission from the providing subgraph is needed. +any subgraph can use `@requires` to declare a dependency on another subgraph's field. +The router fetches the field automatically without explicit permission from the providing subgraph. For fields containing regulated or personally identifiable information, -this means another team's subgraph could gain access to protected data -without an explicit handshake. +another team's subgraph could access protected data without an explicit handshake. With `@openfed__requireFetchReasons`, -the providing subgraph can inspect every incoming request to see whether a field -was requested by the end user or by another subgraph, -and which subgraph it was. -This allows the subgraph to maintain an allow list of subgraphs -that are permitted to access specific fields, -ensuring the data owner stays compliant with regulations. +the providing subgraph can inspect each incoming request to determine whether a field was requested by the end user or by another subgraph. +The subgraph can maintain an allow list of permitted subgraphs for specific fields.As per coding guidelines, prefer short, declarative sentences and avoid over-explanation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/federation/directives/openfed__requirefetchreasons.mdx` around lines 29 - 44, The paragraph explaining the compliance use-case for `@openfed__requireFetchReasons` and `@requires` uses long, comma-heavy sentences and should be rewritten into short, declarative sentences: split compound sentences into separate lines, remove redundant phrases (e.g., "this means"/"allow list"), and state the core points plainly — (1) `@requires` lets a subgraph request fields from another subgraph via the router; (2) that can expose regulated or PII fields to other teams without explicit consent; (3) `@openfed__requireFetchReasons` lets the providing subgraph see who requested a field (end user vs. subgraph) and which subgraph requested it; (4) the subgraph can then enforce an allow list to control access. Use these points to replace the original paragraph with concise sentences.docs-website/federation/directives/connect__fieldresolver.mdx (1)
29-34: Consider splitting the long example sentence.Lines 29-34 form a single sentence with multiple comma-separated clauses. As per coding guidelines, prefer short, declarative sentences.
✏️ Suggested split
-For example, -`id` and `price` on a `Product` type might come from a local database, -while `shippingEstimate` requires a call to an external shipping service -with higher latency. -By annotating `shippingEstimate` with `@connect__fieldResolver`, -the router only calls the shipping service when the client actually requests that field. +For example: +`id` and `price` on a `Product` type might come from a local database. +`shippingEstimate` requires a call to an external shipping service with higher latency. +Annotating `shippingEstimate` with `@connect__fieldResolver` ensures +the router only calls the shipping service when the client requests that field.As per coding guidelines, prefer short, declarative sentences when a sentence has more than one comma-separated clause.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/federation/directives/connect__fieldresolver.mdx` around lines 29 - 34, The long example sentence explaining `@connect__fieldResolver` should be split into shorter declarative sentences: locate the paragraph that begins "For example, `id` and `price` on a `Product` type..." and break it into two or three sentences such as stating where `id` and `price` come from (local DB) in one sentence, explaining that `shippingEstimate` requires an external call in a second sentence, and then a final sentence that explains annotating `shippingEstimate` with `@connect__fieldResolver` causes the router to call the shipping service only when that field is requested; keep wording concise and preserve the original technical terms (`Product`, `id`, `price`, `shippingEstimate`, `@connect__fieldResolver`, "router").
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs-website/federation/directives/connect__fieldresolver.mdx`:
- Around line 29-34: The long example sentence explaining
`@connect__fieldResolver` should be split into shorter declarative sentences:
locate the paragraph that begins "For example, `id` and `price` on a `Product`
type..." and break it into two or three sentences such as stating where `id` and
`price` come from (local DB) in one sentence, explaining that `shippingEstimate`
requires an external call in a second sentence, and then a final sentence that
explains annotating `shippingEstimate` with `@connect__fieldResolver` causes the
router to call the shipping service only when that field is requested; keep
wording concise and preserve the original technical terms (`Product`, `id`,
`price`, `shippingEstimate`, `@connect__fieldResolver`, "router").
In `@docs-website/federation/directives/openfed__requirefetchreasons.mdx`:
- Line 2: Update the page title to match the actual directive name: replace the
current title string "@openfed requireFetchReasons" with the exact directive
identifier "@openfed__requireFetchReasons" so the header matches the directive
symbol used elsewhere (referencing the directive name
`@openfed__requireFetchReasons`).
- Around line 29-44: The paragraph explaining the compliance use-case for
`@openfed__requireFetchReasons` and `@requires` uses long, comma-heavy sentences and
should be rewritten into short, declarative sentences: split compound sentences
into separate lines, remove redundant phrases (e.g., "this means"/"allow list"),
and state the core points plainly — (1) `@requires` lets a subgraph request fields
from another subgraph via the router; (2) that can expose regulated or PII
fields to other teams without explicit consent; (3)
`@openfed__requireFetchReasons` lets the providing subgraph see who requested a
field (end user vs. subgraph) and which subgraph requested it; (4) the subgraph
can then enforce an allow list to control access. Use these points to replace
the original paragraph with concise sentences.
In `@docs-website/federation/directives/specifiedby.mdx`:
- Around line 56-59: Update the specifiedby.mdx text to document the composition
behavior when subgraphs provide different `@specifiedBy` URLs: explain that during
composition the implementation follows a "last-one-wins" merge strategy (as
implemented in extendSchema/extendSchema.ts), so the URL from the last-applied
subgraph will be preserved in the composed schema's specifiedByURL; mention this
explicitly alongside the existing guidance that subgraphs should use the same
URL to avoid surprises.
- Around line 23-26: The long sentence "It provides a machine-readable link
between a custom scalar type and the document that describes its serialization,
coercion, and validation rules." should be split into shorter declarative
sentences; edit the text so the first sentence states that it provides a
machine-readable link between a custom scalar type and the document that
describes its serialization, and follow with one or two short sentences that
state the document also describes coercion and validation rules (e.g., split
into "It provides a machine-readable link between a custom scalar type and the
document that describes its serialization. The document also describes coercion
and validation rules.").
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 34360c94-aa64-4ddf-89e5-b74ce7226bf5
📒 Files selected for processing (6)
docs-website/docs.jsondocs-website/federation/directives/connect__fieldresolver.mdxdocs-website/federation/directives/deprecated.mdxdocs-website/federation/directives/openfed__requirefetchreasons.mdxdocs-website/federation/directives/specifiedby.mdxdocs-website/federation/federation-directives-index.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
@deprecatedfor marking deprecated schema elements,@specifiedByfor custom scalar specifications,@connect__fieldResolverfor routing field resolution through gRPC, and@openfed__requireFetchReasonsfor fetch reason propagation. Updated the directives reference index.