Skip to main content

add spec edits for references

At a glance​

Timeline​

References (soft aliases?) are an alternative syntax for fragment metafields such as __fulfilled

The goal is to create an easily manageable way of requesting different types of fragment spread signals. Multiple metafields or signals will likely be necessary, as after incremental delivery lands, operation writers might be interested in whether a spread has been collected, which can be signaled immediately, or whether all of its fields have been delivered, which may happen only later if the spread has been deferred.

references collect all of these potential signals into a single locus within the response ("the reference") and use "selection set"-style syntax to indicate which signals are of interest. For example, after incremental delivery lands, the following might be valid:

query FragmentReferences {
  nodes(ids: [1, 42]) {
    id
    UserFields { selected }: ...userFragment
    SuperUserFields { selected completed}: ...superUserFragment @defer
  }
}

fragment userFragment on User {
  friends {
    count
  }
}

fragment superUserFragment on SuperUser {
  privilegeLevel
}

This would yield the following data right away:

{
  "nodes": [
    {
      "id": 1,
      "UserFields": { "selected": null },
      "friends": { "count": 1234 }
    },
    {
      "id": 42,
      "UserFields": { "selected": null },
      "friends": { "count": 5678 },
      "SuperUserFields": { "selected": null },
    }
  ]
}

And the following additional payload at path nodes.1 when the deferred fields complete:

{
  "SuperUserFields": { "completed": null },
  "privilegeLevel": 20
}

The existing spec edits only describe the "selected" signal. I am working on the completed signal alongside a version of incremental delivery that does not branch execution or duplicate fields.