Skip to content

Commit b6b6636

Browse files
magicmarkmagicmark
committed
RFC: Field coordinates
1 parent 478adf3 commit b6b6636

File tree

4 files changed

+407
-0
lines changed

4 files changed

+407
-0
lines changed

‎rfcs/FieldCoodinateSerialization.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# RFC: Field Coordinate Serialization
2+
3+
_This is a sister RFC to [RFC: Field Coordinates](./FieldCoordinates.md). This
4+
document assumes knowledge of the Field Coordinates RFC._
5+
6+
This RFC outlines the seralization of field nodes in a GraphQL query to ["field
7+
coordinates"](./FieldCoordinates.md).
8+
9+
## 📜 Problem Statement
10+
11+
Third party GraphQL tooling and libraries may wish to refer to a field, or set of
12+
fields refered to in a document (e.g. query, mutation or subscription). Use cases include documentation, metrics and logging libraries.
13+
14+
![](https://i.fluffy.cc/g78sJCjCJ0MsbNPhvgPXP46Kh9knBCKF.png)
15+
16+
_(Field coordinates shown in a query - [Apollo Studio](https://www.apollographql.com/docs/studio/)_)
17+
18+
There already exists a convention used by some third party libraries for
19+
calculating field coordinates in a query. However, there is no formal
20+
specification or name for this convention.
21+
22+
This RFC proposes standardization for computing field coordinates.
23+
24+
## 🐕 Worked Example
25+
26+
Consier the following schema:
27+
28+
```graphql
29+
type Person {
30+
name: String
31+
}
32+
33+
type Business {
34+
name: String
35+
owner: Person
36+
}
37+
38+
type Query {
39+
searchBusiness(name: String): [Business]
40+
}
41+
```
42+
43+
And the following query:
44+
45+
```graphql
46+
query {
47+
searchBusinesses(name: "El Greco Deli") {
48+
name
49+
owner {
50+
name
51+
}
52+
}
53+
}
54+
```
55+
56+
A GraphQL server may wish to log which fields are accessed in a query, such that
57+
we can compute a list of "most popular fields" in the schema. We may then want to
58+
use this list to optimize the most frequently accessed fields in our schea.
59+
60+
Field coordinates allow us to store this list of "most popular fields".
61+
62+
We want a way to calculate field coordinates from a given field node (and by
63+
extension, calculate a list of all field coordinates contained in a document).
64+
65+
From the query above, we would calculate the following list of field coordinates:
66+
67+
- `Query.searchBusinesses`
68+
- `Business.name`
69+
- `Business.owner`
70+
- `Person.name`
71+
72+
## Examples in industry
73+
74+
- [Apollo Studio](https://www.apollographql.com/docs/studio/) shows field
75+
coodinates when hovering over fields in a query:
76+
77+
![](https://i.fluffy.cc/g78sJCjCJ0MsbNPhvgPXP46Kh9knBCKF.png)
78+
79+
- [extract-field-coordinates](https://github.com/sharkcore/extract-field-coordinates)
80+
extracts a list of field coordinates from a schema and query document.
81+
82+
## Drawbacks
83+
84+
- Requires the corresponding schema as an input to be able to calculate the field
85+
coordinate
86+
87+
- **Edge Cases:** There are some edge cases where we need to decide (or let the
88+
user decide) behaviour:
89+
90+
- What happens when the schema is outdated or a type referenced in the query is
91+
not present in the schema? Do we throw an error as the document/schema is
92+
invalid, or do we try a "best effort" approach to preserve as much information
93+
as possible?
94+
95+
- TODO: add more edge case behaviour from the [sample implementation](https://github.com/sharkcore/extract-field-coordinates)
96+
97+
## Alternatives Considered
98+
99+
### Field Paths
100+
101+
[`path` exists as an attribute on `GraphQLResolveInfo`](https://github.com/graphql/graphql-js/blob/8f3d09b54260565/src/type/definition.js#L951).
102+
103+
Given the following query:
104+
105+
```graphql
106+
query {
107+
searchBusinesses(name: "El Greco Deli") {
108+
name
109+
owner {
110+
name
111+
}
112+
}
113+
}
114+
```
115+
116+
The field coordinate `Person.name` may also be written as the following field
117+
path:
118+
119+
```json
120+
["query", "searchBusinesses", 1, "owner", "name"]
121+
```
122+
123+
- Like field coordinates, this uniquely identifies the "name" field and
124+
disambiguates it from the "name" field on the `Business` type.
125+
- Note that we also didn't need a schema to calculate the field path - this can
126+
be with just the query document.
127+
128+
However - we are unable to tell from a field path alone what the parent _type_
129+
was.
130+
131+
Consider the following query:
132+
133+
```graphql
134+
query {
135+
getUsers(name: "mark") {
136+
name
137+
}
138+
}
139+
```
140+
141+
The same field coordinate `Person.name` in the context of this query would be
142+
written as:
143+
144+
```json
145+
["query", "getUsers", 1, "name"]
146+
```
147+
148+
Field Paths alone are insufficient to do normalization of the field nodes. We
149+
need the parent type information from the schema to work out that both of these
150+
field paths reference the same field in the schema.

‎rfcs/FieldCoordinates.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# RFC: Field Coordinates
2+
3+
**Champion:** @magicmark
4+
5+
This RFC proposes formalizing "field coordinates" - a way to uniquely identify a
6+
field defined in a GraphQL Schema.
7+
8+
This may be listed as an appendix item in the official specification to serve as
9+
an official reference to third party library implementations.
10+
11+
## 🚫 What this RFC does _not_ propose
12+
13+
This RFC does not seek to change the GraphQL language in any way.
14+
15+
- There are **no proposed GraphQL runtime changes**
16+
- There are **no proposed changes to how we parse documents**.
17+
18+
## 📜 Problem Statement
19+
20+
Third party GraphQL tooling and libraries may wish to refer to a field, or set of
21+
fields in a schema. Use cases include documentation, metrics and logging
22+
libraries.
23+
24+
![](https://i.fluffy.cc/5Cz9cpwLVsH1FsSF9VPVLwXvwrGpNh7q.png)
25+
26+
_(Example shown from GraphiQL's documentation search tab)_
27+
28+
There already exists a convention used by some third party libraries for writing
29+
out fields in a unique way for such purposes. However, there is no formal
30+
specification or name for this convention.
31+
32+
## ✨ Worked Example
33+
34+
For example, consider the following schema:
35+
36+
```graphql
37+
type Person {
38+
name: String
39+
}
40+
41+
type Business {
42+
name: String
43+
owner: Person
44+
}
45+
46+
type Query {
47+
searchBusinesses(name: String): [Business]
48+
}
49+
```
50+
51+
We can write the following list of field coordinates:
52+
53+
- `Person.name` uniquely identifies the "name" field on the "Person" type
54+
- `Business.name` uniquely identifies the "name" field on the "Business"
55+
type
56+
- `Business.owner` uniquely identifies the "owner" field on the "Business" type
57+
- `Query.searchBusinesses` uniquely identifies the "searchBusinesses" field on
58+
the "Query" type
59+
60+
This RFC standardizes how we write field coodinates as above.
61+
62+
## 🎨 Prior art
63+
64+
- The name "field coordinates" comes from [GraphQL Java](https://github.com/graphql-java/graphql-java)
65+
(4.3k stars), where this is already used as described - [Github comment](https://github.com/graphql/graphql-spec/issues/735#issuecomment-646979049) - [Implementation](https://github.com/graphql-java/graphql-java/blob/2acb557474ca73/src/main/java/graphql/schema/FieldCoordinates.java)
66+
67+
- GraphiQL displays field coordinates in its documentation search tab:
68+
69+
![](https://i.fluffy.cc/5Cz9cpwLVsH1FsSF9VPVLwXvwrGpNh7q.png)
70+
71+
- [GraphQL Inspector](https://github.com/kamilkisiela/graphql-inspector) (840 stars) shows type/field pairs in its output:
72+
73+
![](https://i.imgur.com/HAf18rz.png)
74+
75+
- [Apollo Studio](https://www.apollographql.com/docs/studio/) shows field
76+
coodinates when hovering over fields in a query:
77+
78+
![](https://i.fluffy.cc/g78sJCjCJ0MsbNPhvgPXP46Kh9knBCKF.png)
79+
80+
## 🗳️ Alternatives considered
81+
82+
### Naming
83+
84+
- "type/field pairs" was the original suggestion
85+
86+
However, "field coordinates" was chosen as it is already understood and used by
87+
the popular [GraphQL Java](https://github.com/graphql-java/graphql-java)
88+
project.
89+
90+
- "Field path" / "GraphQL path"
91+
92+
[`path` exists as an attribute on `GraphQLResolveInfo`](https://github.com/graphql/graphql-js/blob/8f3d09b54260565/src/type/definition.js#L951).
93+
94+
Given the following query:
95+
96+
```graphql
97+
query {
98+
searchBusinesses(name: "El Greco Deli") {
99+
name
100+
owner {
101+
name
102+
}
103+
}
104+
}
105+
```
106+
107+
The field coordinate `Person.name` may also be written as the following field
108+
path:
109+
110+
```json
111+
["query", "searchBusinesses", 1, "owner", "name"]
112+
```
113+
114+
Note that here, the "path" is a serialized _response_ tree traversal, instead
115+
of describing the location of the field in the _schema_.
116+
117+
Since "path" is already used in GraphQL nonclemanture to describe the location
118+
of a field in a response, we'll avoid overloading this term.
119+
120+
### Separator
121+
122+
This RFC proposes using "`.`" as the separator character. The following have
123+
also been proposed:
124+
125+
- `Foo::bar`
126+
- `Foo#bar`
127+
- `Foo->bar`
128+
- `Foo~bar`
129+
- `Foo:bar`
130+
131+
"`.`" is already used in the existing implementations of field coordinates, hence
132+
the suggested usage in this RFC. However, we may wish to consider one of the
133+
alternatives above, should this conflict with existing or planned language
134+
features.
135+
136+
## 🤔 Drawbacks / Open questions
137+
138+
- https://github.com/graphql/graphql-spec/issues/735 discusses potential
139+
conflicts with the upcoming namespaces proposal - would like to seek clarity on
140+
this
141+
142+
- **Is this extensible enough?** The above issue discusses adding arguments as
143+
part of this specifcation - we haven't touched on this here in order to keep
144+
this RFC small, but we may wish to consider this in the future (e.g.
145+
`Query.searchBusiness:name`).
146+
147+
- **How will this play with namespaces?** Not sure what this looks like yet!
148+
149+
- **Would we want to add a method to graphql-js?** A `fieldCoordinateToFieldNode`
150+
method (for example) may take in a field coordinate string and return a field
151+
AST node to serve as a helper / reference implementation of the algorithm to
152+
look up the field node.

0 commit comments

Comments
 (0)