From 2c4ed1ef08fc506fd1d1cd63adad916e24011a2a Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Fri, 28 Oct 2016 16:00:03 -0700 Subject: [PATCH 1/3] Add RFC sketch for __id for discussion --- .gitignore | 1 + rfcs/__id.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 rfcs/__id.md diff --git a/.gitignore b/.gitignore index 3eddd41e3..96cbdea4a 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ build out node_modules npm-debug.log +.vscode diff --git a/rfcs/__id.md b/rfcs/__id.md new file mode 100644 index 000000000..e969ad43d --- /dev/null +++ b/rfcs/__id.md @@ -0,0 +1,60 @@ +# `__id`, a common unique ID field for object types + +## Justification + +Most GraphQL clients do some kind of result normalization to improve UI +consistency across multiple GraphQL results. Currently, these clients need to be +configured to use a specific field name, or require server implementers to use a +particular field name like `id` by convention. + +## Desirable properties + +### Unique meta field name + +Naming the meta field `__id` with leading underscores is important to avoid +overlapping with any existing field, and many types already provide a field +named `id`. If it's important that a client receives this field with a different +specific name, an alias can be used to do so, but otherwise this leaves +the ability for any Type to present fields of any name while presenting an +unambiguous field to access a globally unique identifier. + +### Queryable on every type + +It's advantageous for the `__id` field to be queryable on every type of the +schema, just like `__typename`, so that client-side tools can ask for a unique +identifier even if they don't have access to the schema ahead of time. This +proposal suggests simply having the `__id` field return the `ID` type, which is +nullable. In the case where the type doesn't support a unique identifier, it can +return `null` for that field, which indicates that this object doesn't have an +ID and the client should not attempt to normalize it. + +### Globally unique + +Since this field in the schema is GraphQL-specific, we have an opportunity to +introduce a requirement that will make it far easy to build deduplicating and +caching features on the client. Requiring identifiers returned from `__id` to be +globally unique across all types in the schema means that clients don't need to +do any post-processing on the results to generate cache keys. Since the `__id` +field name is unlikely to collide with any existing non-unique `id` fields, for +example from SQL, developers can have both fields side-by-side in the result +where necessary. + +### Validation changes - allow `__id` on all unions and interfaces + +Just like `__typename` can be queried on any union or interface selection set, +`__id` can as well. If some of the results in an array of union or interface +types have valid `__id`s and some don't, then some of the results will have +`null` for that field. + +## Non-goals + +### Refetchability. + +This proposal intentionally does not address refetching any object directly +given it's `__id` value. Experience building Facebook's type system and others +exposed numerous examples of types for which a refetch token and a unique cache +key were not the same thing. This proposal focusing only on the use case of +uniquely identifying objects to use for caching and deduplicating +result values. + +> Credit to Lee Byron for some of the initial content. From a07e0c9d3a0bef4959ca5dfc457f9ea6a2df7178 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Fri, 28 Oct 2016 16:05:15 -0700 Subject: [PATCH 2/3] Add some extra points --- rfcs/__id.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/rfcs/__id.md b/rfcs/__id.md index e969ad43d..1f4254ad0 100644 --- a/rfcs/__id.md +++ b/rfcs/__id.md @@ -46,6 +46,10 @@ Just like `__typename` can be queried on any union or interface selection set, types have valid `__id`s and some don't, then some of the results will have `null` for that field. +### Exposing whether or not an ID will be returned via introspection + +There might be cache implementations which would get an efficiency benefit from knowing which types have unique IDs before receiving a result from the server. GraphQL type definitions should have a way of specifying whether or not they support a unique ID so that clients can choose to introspect this feature if it is useful. + ## Non-goals ### Refetchability. @@ -57,4 +61,10 @@ key were not the same thing. This proposal focusing only on the use case of uniquely identifying objects to use for caching and deduplicating result values. +## Remaining questions + +### Dealing with absent IDs + +In previous proposals for this feature, there was the idea that the `__id` feature would simply be omitted from the response if the object being queried didn't have one. I think the most reasonable thing to do is to use GraphQL's existing concept of a nullable type, and just return `null` when no ID is available. + > Credit to Lee Byron for some of the initial content. From c2f2b8e0ba66e774ef17f5dc638920831c595fc1 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Mon, 31 Oct 2016 11:37:54 -0700 Subject: [PATCH 3/3] Remove .vscode from gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 96cbdea4a..3eddd41e3 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,3 @@ build out node_modules npm-debug.log -.vscode