Update description of Fragments to emphasize evolving data needs

[janettec]

Why these changes?

Fragments are not for reuse.

The current language in section 2.8 on Fragments, namely the sentence...

Fragments allow for the reuse of common repeated selections of fields, reducing duplicated text in the document.

...encourages using fragments to deduplicate common selections, even if those selections represent independent data needs.

For example, let's consider these two functions

// This function formats a post for display in a feed
func formatPostForFeed(post: PostDisplayFragment) -> String {
 let authorName = post.author.name
 let contentText = post.content.text

 return "\(authorName) posted: \(contentText)"
}

// This function formats a post for notification purposes
func formatPostForNotification(post: PostDisplayFragment) -> String {
 let authorName = post.author.name
 let contentText = post.content.text

 return "New post from \(authorName): \(contentText)"
}

Given these two functions currently both use authorName and contentText, the current language in the spec encourages one to write a fragment

fragment PostDisplayFragment on Post {
 author
 content
}

If formatPostForFeed now needs timestamp, we will add naturally add timestamp to PostDisplayFragment

// This function formats a post for display in a feed
func formatPostForFeed(post: PostDisplayFragment) -> String {
 let authorName = post.author.name
 let contentText = post.content.text
 let timestamp = post.createdAt.formatted // Added

 return "\(authorName) posted: \(contentText)\nPosted \(timestamp)"
}

fragment PostDisplayFragment on Post {
 author
 content
 timestamp # Added
}

If we have the following queries

query NotificationQuery {
 ...PostDisplayFragment # Over-fetching timestamp
}

query FeedQuery {
 ...PostDisplayFragment
}

notice how NotificationQuery is now over-fetching timestamp!

The key observation is that formatPostForFeed and formatPostForNotification are two independent functions, so by having them both rely on a single fragment to express their data needs, we are creating a dependency where one should not exist (because that dependency does not exist in the product logic itself).

What are the proposed changes?

Updated:

1. The description for why one might use fragments
2. The first GraphQL example in section 2.8

The goal is to emphasize that fragments support evolving data needs (as opposed to recommending people identify common selections that are currently in an executable document).

Open to any and all feedback on the motivation for the change and how it's communicated via changes in the spec language!

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	4dc59ca
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/68cd8ef02819b70008a6a958
😎 Deploy Preview	https://deploy-preview-1193--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[benjie]

Definitely agree on the motivation for this change; thanks for the submission Janette!

[andimarek]

I think that is is great change overall. The challenge is a bit to make it understandable in the context of the spec.

Using fragments to declare data needs (like in relay) always requires something on top of the spec to make it work. So we would have to make this clear somehow.

[martinbonnin]

A couple comments but otherwise very supportive of updating that language!

[benjie]

Calling the logic friendProfile and the fragment friendProfile is confusing. Can we differentiate the logic - e.g. just call it "profile rendering logic" (prose) rather than using code? (Not sure if this is the best fix.)

[Keweiqu]

Need to flush out what modular means. Matt + Pascal's suggestion: single purpose.

[benjie]

Maybe something along the lines of (written whilst on Zoom, not final wording!):

Fragments allow client components and logic to describe their specific
data requirements locally. Fragments can then be composed together to
form a GraphQL operation to issue to the server.