Skip to main content

Fragment Arguments (parameterized fragments) for GraphQL

At a glance​

Timeline​

This is a proposal to bring Relay-style Fragment Arguments into the Spec as an optional, client-only language feature.

Overview

We would allow clients to write GraphQL like:

query Q1 {
  ...Number(x: 100)
}

query Q2($i: Int = 3) {
  ...Number(x: $i)
}

fragment Number($x: Int!) on Query {
  number(value: $x)
}

which would, prior to sending to the server, be transformed into two unique queries that current spec-compliant servers would understand, such that it behaved like the queries were written like:

query Q1 {
  ...Number
}

fragment Number on Query {
  number(value: 100)
}

and

query Q2($i: Int = 3) {
  ...Number
}

fragment Number on Query {
  number(value: $i)
}

The exact mechanics of how the query gets rewritten could be different per client, but the behavior should be identical. This RFC seeks to describe the new syntax, as well as adding additional validation for clients that choose to support fragment arguments.

Background

Relay has seen a lot of usage of their non-spec-compliant @arguments and @argumentDefinitions directives, but they're both cumbersome to use and fail basic Spec validation (directives with arguments used but never defined). They accomplish this by pre-compiling any GraphQL definitions using @arguments and @argumentDefinitions to transform the document such that, by the time it's sent to the server, it is spec compliant. However, Relay's user-facing directives both do not conform to the spec and also provide a pretty cumbersome, somewhat unintuitive user-facing design.

This proposal is to allow clients that pre-compile their GraphQL prior to sending it to the server (such as Relay) to have a built-in syntax for passing argument values into fragment spreads for fragments with well-defined argument definitions.

Champion: @mjmahone