GraphQL RFC Tracker

RFC 3 / Accepted

Update description of Fragments to emphasize evolving data needs

Opened on2025-09-12
Merged on2026-02-05

At a glance

Spec PR description

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!

Timeline