From 5cf74db06e9660efb96cf0e82e70159f722aab4f Mon Sep 17 00:00:00 2001 From: Janette Cheng Date: Fri, 12 Sep 2025 14:57:38 -0400 Subject: [PATCH 1/5] Update the description for when to use a fragment --- spec/Section 2 -- Language.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 94b99f20d..aabf60eb1 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -587,13 +587,9 @@ FragmentName : Name but not `on` Fragments are the primary unit of composition in GraphQL. -Fragments allow for the reuse of common repeated selections of fields, reducing -duplicated text in the document. Inline Fragments can be used directly within a -selection to condition upon a type condition when querying against an interface -or union. +Fragments allow for the definition of selection sets that are colocated with the logic that requires those selections, making it easier to add and remove selections as needed. -For example, if we wanted to fetch some common information about mutual friends -as well as friends of some user: +For example, if we have some `friendProfile` logic that requires `id`, `name`, and `profilePic`, and we want to apply that logic to the mutual friends as well as friends of some user: ```graphql example query noFragments { @@ -612,28 +608,32 @@ query noFragments { } ``` -The repeated fields could be extracted into a fragment and composed by a parent -fragment or operation. +The fields required of `friendProfile` can be extracted into a fragment and composed +by a parent fragment or operation. ```graphql example query withFragments { user(id: 4) { friends(first: 10) { - ...friendFields + ...friendProfileFragment } mutualFriends(first: 10) { - ...friendFields + ...friendProfileFragment } } } - -"Common fields for a user's friends." -fragment friendFields on User { +``` +```graphql example +"Fields required to display a friend's profile" +fragment friendProfileFragment on User { id name profilePic(size: 50) } ``` +If `friendProfile` no longer needs `name`, the `name` field can be removed from +`friendProfileFragment` and it will no longer be fetched in both locations the +fragment is consumed. Fragments are consumed by using the spread operator (`...`). All fields selected by the fragment will be added to the field selection at the same level as the From 992fb158a5e3d5c4f54ee87c8bc5c6bfa99a78cc Mon Sep 17 00:00:00 2001 From: Janette Cheng Date: Fri, 12 Sep 2025 16:03:09 -0400 Subject: [PATCH 2/5] some small edits for new lines + updating a word --- spec/Section 2 -- Language.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index aabf60eb1..82137e72d 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -587,9 +587,13 @@ FragmentName : Name but not `on` Fragments are the primary unit of composition in GraphQL. -Fragments allow for the definition of selection sets that are colocated with the logic that requires those selections, making it easier to add and remove selections as needed. +Fragments allow for the definition of selection sets that are colocated with the +logic that requires those selections, making it easier to add and remove selections +as needed. -For example, if we have some `friendProfile` logic that requires `id`, `name`, and `profilePic`, and we want to apply that logic to the mutual friends as well as friends of some user: +For example, if we have some `friendProfile` logic that requires `id`, `name`, +and `profilePic`, and we want to apply that logic to the mutual friends as well +as friends of some user: ```graphql example query noFragments { @@ -608,8 +612,8 @@ query noFragments { } ``` -The fields required of `friendProfile` can be extracted into a fragment and composed -by a parent fragment or operation. +The fields required by `friendProfile` can be extracted into a fragment and +composed by a parent fragment or operation. ```graphql example query withFragments { From 12793fc9604b07cca5830336582843cf1755c653 Mon Sep 17 00:00:00 2001 From: Janette Cheng Date: Fri, 19 Sep 2025 11:51:19 -0400 Subject: [PATCH 3/5] Simplify language and remove reference to 'colocation' --- spec/Section 2 -- Language.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 82137e72d..bfb9bed92 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -587,12 +587,11 @@ FragmentName : Name but not `on` Fragments are the primary unit of composition in GraphQL. -Fragments allow for the definition of selection sets that are colocated with the -logic that requires those selections, making it easier to add and remove selections -as needed. +Fragments allow for the definition of modular selection sets that make it easier +to add and remove selections as needed. -For example, if we have some `friendProfile` logic that requires `id`, `name`, -and `profilePic`, and we want to apply that logic to the mutual friends as well +For example, if we have some `friendProfile` logic that requires `id`, `name`, +and `profilePic`, and we want to apply that logic to the mutual friends as well as friends of some user: ```graphql example @@ -612,31 +611,31 @@ query noFragments { } ``` -The fields required by `friendProfile` can be extracted into a fragment and +The fields required by `friendProfile` can be extracted into a fragment and composed by a parent fragment or operation. ```graphql example query withFragments { user(id: 4) { friends(first: 10) { - ...friendProfileFragment + ...friendProfile } mutualFriends(first: 10) { - ...friendProfileFragment + ...friendProfile } } } ``` ```graphql example "Fields required to display a friend's profile" -fragment friendProfileFragment on User { +fragment friendProfile on User { id name profilePic(size: 50) } ``` -If `friendProfile` no longer needs `name`, the `name` field can be removed from -`friendProfileFragment` and it will no longer be fetched in both locations the +If `friendProfile` no longer needs `name`, the `name` field can be removed from +the `friendProfile` fragment and it will no longer be fetched in both locations the fragment is consumed. Fragments are consumed by using the spread operator (`...`). All fields selected From 4dc59ca4b9b24060fa664a9ce0b3addc47b7d4b0 Mon Sep 17 00:00:00 2001 From: Janette Cheng Date: Fri, 19 Sep 2025 13:12:10 -0400 Subject: [PATCH 4/5] format --- spec/Section 2 -- Language.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index bfb9bed92..5ed35505f 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -626,6 +626,7 @@ query withFragments { } } ``` + ```graphql example "Fields required to display a friend's profile" fragment friendProfile on User { @@ -634,9 +635,10 @@ fragment friendProfile on User { profilePic(size: 50) } ``` + If `friendProfile` no longer needs `name`, the `name` field can be removed from -the `friendProfile` fragment and it will no longer be fetched in both locations the -fragment is consumed. +the `friendProfile` fragment and it will no longer be fetched in both locations +the fragment is consumed. Fragments are consumed by using the spread operator (`...`). All fields selected by the fragment will be added to the field selection at the same level as the From df32811fe9141d99f047079df7272e5d5ce438e9 Mon Sep 17 00:00:00 2001 From: Janette Cheng Date: Fri, 10 Oct 2025 12:34:43 -0400 Subject: [PATCH 5/5] Respond to feedback from last working group meeting --- spec/Section 2 -- Language.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 5ed35505f..f1ff5ff00 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -587,12 +587,13 @@ FragmentName : Name but not `on` Fragments are the primary unit of composition in GraphQL. -Fragments allow for the definition of modular selection sets that make it easier -to add and remove selections as needed. +Each client component should declare its data needs in a dedicated fragment. +These fragments may then be composed in the same fashion as the components +themselves to form a GraphQL operation to issue to the server. -For example, if we have some `friendProfile` logic that requires `id`, `name`, -and `profilePic`, and we want to apply that logic to the mutual friends as well -as friends of some user: +For example, if we have some logic that requires `id`, `name`, and `profilePic` +to render a profile, and we want to apply that logic to the friends and mutual +friends of a user: ```graphql example query noFragments { @@ -611,7 +612,7 @@ query noFragments { } ``` -The fields required by `friendProfile` can be extracted into a fragment and +The fields required to render a profile can be extracted into a fragment and composed by a parent fragment or operation. ```graphql example @@ -628,7 +629,7 @@ query withFragments { ``` ```graphql example -"Fields required to display a friend's profile" +"Fields required to render a friend's profile" fragment friendProfile on User { id name @@ -636,9 +637,9 @@ fragment friendProfile on User { } ``` -If `friendProfile` no longer needs `name`, the `name` field can be removed from -the `friendProfile` fragment and it will no longer be fetched in both locations -the fragment is consumed. +If the profile rendering logic no longer needs `name`, the `name` field can be +removed from the `friendProfile` fragment and it will no longer be fetched in +both locations the fragment is consumed. Fragments are consumed by using the spread operator (`...`). All fields selected by the fragment will be added to the field selection at the same level as the