Schema Coordinates by magicmark · Pull Request #794 · graphql/graphql-spec

magicmark · 2020-11-18T07:11:07Z

👋

I've pulled out the proposed spec edits for Schema Coordinates (issue: #735) into this PR.

(The RFC now lives in the original PR: https://github.com/graphql/graphql-spec/pull/746/files)

@leebyron you mentioned it might be possible to simplify the grammar - I played around a bit since the original PR, but I think I need some help here. What did you have in mind?

As suggested, tagging @eapache @mjmahone as additional reviewers as we had some good conversation in last WG meeting about this.

Thanks!

GraphQL.js PR: graphql/graphql-js#3044

magicmark · 2020-11-18T07:15:50Z

Oh also, here's another option I had for the examples table, was thinking it might be good to explicitly show all the different kinds of schema you can select:

felt slightly too verbose to me, but curious to see if anyone prefers this

benjie

Thanks for your hard work on this!

benjie

Looks good to me; a few optional tweaks suggested.

magicmark · 2021-01-04T08:14:35Z

+Schema Coordinates are always unique. Each type, field, argument, enum value, or
+directive may be referenced by exactly one possible Schema Coordinate.


feels like something worth highlighting and being clear about as a guarantee in the spec

magicmark · 2021-01-04T08:17:05Z

+For example, the following is *not* a valid Schema Coordinate:
+
+```graphql counter-example
+Entity.Business
+```
+
+In this counter example, both `Entity.Business` and `Business` would refer to
+the `Business` type. Since it would be ambiguous what the "primary key" should
+be in an application that uses Schema Coordinates to reference types, this is
+not allowed.


is this waffle? thought it might be helpful to have a little explanation/demonstration of this property

Could just be

- Since it would be ambiguous what the "primary key" should be in an application that uses Schema Coordinates to reference types, this is not allowed. + Such ambiguity is disallowed (and hence why this is is invalid syntax).

(More terse, but doesn't walk the reader through why this is bad)

Voting lines are now open!

In this counter example, Entity.Business is redundant since Business already uniquely identifies the Business type. Such redundancy is disallowed by this spec - every type, field, field argument, enum value, directive, and directive argument has exactly one canonical Schema Coordinate.

👍 thanks benjie, stealing this wording

Happy new year! 🥳 It's possible we still want more time for the RFC to marinate, but I'll attend so I can be available to folks to discuss the schema coordinates rfc/spec edit in person. graphql/graphql-spec#794 Thanks!

mcohen75 · 2021-02-04T18:10:35Z

At Indeed we log usage of schema elements to 1) support deprecation and 2) understand usage from a product management perspective (i.e. is this API we built adding value?).

We defined our own coordinate system that is not quite as complete as this spec. A nice benefit of formalizing a coordinate system is that shared tools can be built to solve these and other use cases.

👍 👍 👍

leebyron · 2021-04-14T01:01:00Z

I made some fairly significant edits to the prose and examples section in an attempt to simplify. @magicmark please take a look and let me know what you think.

leebyron · 2021-04-14T21:30:27Z

IIRC the only thing holding this from Approval stage is a landed GraphQL.js PR?

Co-authored-by: Benjie <benjie@jemjie.com>

benjie · 2025-07-04T16:33:10Z

@magicmark Here's my original diff that I drafted up locally:

diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md
index e422d9a..7a6dc1f 100644
--- a/spec/Section 2 -- Language.md	
+++ b/spec/Section 2 -- Language.md	
@@ -113,6 +113,8 @@ Comments are {Ignored} like white space and may appear after any token, or
 before a {LineTerminator}, and have no significance to the semantic meaning of a
 GraphQL Document.
 
+Comments are forbidden within a _schema coordinate_.
+
 ### Insignificant Commas
 
 Comma :: ,
@@ -154,25 +156,27 @@ Ignored ::
 - Comma
 
 {Ignored} tokens are used to improve readability and provide separation between
-lexical tokens, but are otherwise insignificant and not referenced in
-syntactical grammar productions.
+lexical tokens in a GraphQL document, but are otherwise insignificant and not
+referenced in syntactical grammar productions. {Ignored} are forbidden within a
+_schema coordinate_.
 
-Any amount of {Ignored} may appear before and after every lexical token. No
-ignored regions of a source document are significant, however {SourceCharacter}
-which appear in {Ignored} may also appear within a lexical {Token} in a
-significant way, for example a {StringValue} may contain white space characters.
-No {Ignored} may appear _within_ a {Token}, for example no white space
-characters are permitted between the characters defining a {FloatValue}.
+Any amount of {Ignored} may appear before and after every lexical token in a
+GraphQL document. No ignored regions of a source document are significant,
+however {SourceCharacter} which appear in {Ignored} may also appear within a
+lexical {Token} in a significant way, for example a {StringValue} may contain
+white space characters. No {Ignored} may appear _within_ a {Token}, for example
+no white space characters are permitted between the characters defining a
+{FloatValue}.
 
 **Byte Order Mark**
 
 UnicodeBOM :: "Byte Order Mark (U+FEFF)"
 
-The _Byte Order Mark_ is a special Unicode code point which may appear at the
+:: The _Byte Order Mark_ is a special Unicode code point which may appear at the
 beginning of a file which programs may use to determine the fact that the text
 stream is Unicode, and what specific encoding has been used. As files are often
 concatenated, a _Byte Order Mark_ may appear before or after any lexical token
-and is {Ignored}.
+and is {Ignored}. {UnicodeBOM} is forbidden within a _schema coordinate_.
 
 ### Punctuators

Ultimately I decided that section 2 of the spec is about the GraphQL language (for GraphQL documents) which does not specifically relate to schema coordinates, and so instead of talking about schema coordinates in section 2 before they are introduced, I would instead have schema coordinates reference section 2 and apply the exception on top. I'm not sure if this is the right decision - @leebyron would be able to better weigh in here - but if we are to comment in section 2 then here are the kind of changes that I would have made (i.e. adding "in a GraphQL document" to differentiate such from a "schema coordinate").

This reverts commit f4eec91.

…ordinates_spec_edit

magicmark · 2025-07-04T22:48:57Z

ack @benjie

section 2 of the spec is about the GraphQL language (for GraphQL documents) which does not specifically relate to schema coordinates

makes sense, I was wondering about this too. seems overkill I agree, but something may be in order.

Anyway I've removed it from this PR for now, and made a separate follow-up PR that can be merged on top of this, should we decide this clarification (or similar) is appropriate. magicmark#2

magicmark · 2025-08-07T17:10:49Z

Updated the spec + implementation (graphql/graphql-js#4463) per the last meeting.

benjie

Looking good! Here's some editorial changes that I'd recommend

benjie · 2025-08-28T10:51:49Z

Note: I guessed at the anchor tags to use in this; please check they're valid 😅

Co-authored-by: Benjie <benjie@jemjie.com>

Depends on #3115 Implements graphql/graphql-spec#794 Adds: * DOT punctuator in lexer * Improvements to lexer errors around misuse of `.` * Minor improvement to parser core which simplified this addition * `SchemaCoordinate` node and `isSchemaCoodinate()` predicate * Support in `print()` and `visit()` * Added function `parseSchemaCoordinate()` since it is a parser entry point. * Added function `resolveSchemaCoordinate()` and `resolveASTSchemeCoordinate()` which implement the semantics (name mirrored from `buildASTSchema`) as well as the return type `GraphQLSchemaElement` --------- Co-authored-by: Benjie Gillam <benjie@jemjie.com> Co-authored-by: Mark Larah <mark@larah.me> Co-authored-by: Yaacov Rydzinski <yaacovCR@gmail.com>

…QLEnumValue (graphql#4288) this extracts logic from graphql#3044 and graphql#3145 (later rebased as graphql#3807 and [the full schema coordinate RFC](graphql/graphql-spec#794) This is a BREAKING CHANGE because these schema elements are now longer plain objects and function differently in various scenarios, for example with `String(<schemaElement>` `JSON.stringifu(<schemaElement>` and `.toString()` and `.toJSON()` --------- Co-authored-by: Jovi De Croock <decroockjovi@gmail.com>

magicmark mentioned this pull request Nov 18, 2020

RFC: Schema Coordinates #746

Merged

benjie requested changes Nov 18, 2020

View reviewed changes

Comment thread spec/Appendix C -- Schema Coordinates.md Outdated

Comment thread spec/Appendix C -- Schema Coordinates.md Outdated

leebyron reviewed Nov 19, 2020

View reviewed changes

Comment thread spec/Appendix C -- Schema Coordinates.md Outdated

Comment thread spec/Appendix C -- Schema Coordinates.md Outdated

Comment thread spec/Appendix C -- Schema Coordinates.md Outdated

magicmark commented Nov 21, 2020

View reviewed changes

Comment thread spec/Section 3 -- Type System.md Outdated

benjie approved these changes Nov 23, 2020

View reviewed changes

Comment thread spec/Section 3 -- Type System.md Outdated

Comment thread spec/Section 3 -- Type System.md Outdated

Comment thread spec/Section 3 -- Type System.md Outdated

Comment thread spec/Section 3 -- Type System.md Outdated

leebyron reviewed Dec 3, 2020

View reviewed changes

Comment thread spec/Section 3 -- Type System.md Outdated

magicmark commented Jan 4, 2021

View reviewed changes

magicmark mentioned this pull request Jan 4, 2021

Add Mark to January WG meeting graphql/graphql-wg#568

Merged

leebyron added the 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) label Jan 7, 2021

Base automatically changed from master to main February 3, 2021 04:50

leebyron added 📄 Draft (RFC 2) RFC Stage 2 (See CONTRIBUTING.md) and removed 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) labels Mar 4, 2021

michaelstaib mentioned this pull request Mar 4, 2021

Track: Schema Coordinates: add spec edit ChilliCream/graphql-platform#3193

Closed

leebyron added this to the May2021 milestone Apr 13, 2021

leebyron force-pushed the schema_coordinates_spec_edit branch 3 times, most recently from 4f854af to c0b82d5 Compare April 13, 2021 23:57

leebyron force-pushed the schema_coordinates_spec_edit branch 3 times, most recently from 81ef020 to 4299d8c Compare April 14, 2021 01:18

leebyron requested review from a team and benjie April 14, 2021 01:20

leebyron changed the title ~~Schema Coordinates: add spec edit~~ Schema Coordinates Apr 14, 2021

leebyron approved these changes Apr 14, 2021

View reviewed changes

benjie reviewed Jul 4, 2025

View reviewed changes

Comment thread spec/Section 3 -- Type System.md Outdated

magicmark and others added 2 commits July 4, 2025 09:14

Update spec/Section 3 -- Type System.md

33b7562

Co-authored-by: Benjie <benjie@jemjie.com>

Update Section 2 -- Language.md

f4eec91

Revert "Update Section 2 -- Language.md"

e4bdce8

This reverts commit f4eec91.

magicmark force-pushed the schema_coordinates_spec_edit branch from e4bdce8 to c8375f0 Compare July 4, 2025 22:37

Merge branch 'main' of github.com:graphql/graphql-spec into schema_co…

4c39cda

…ordinates_spec_edit

magicmark force-pushed the schema_coordinates_spec_edit branch from c8375f0 to 4c39cda Compare July 4, 2025 22:38

magicmark mentioned this pull request Jul 4, 2025

Add benjie's edit to clarify schema coordinates may not include {Igno… magicmark/graphql-spec#2

Closed

restrict schema coordinates to a unique grammar

fc1ddca

format

63b0933

benjie requested changes Aug 28, 2025

View reviewed changes

Comment thread spec/Appendix B -- Grammar Summary.md

Comment thread spec/Appendix B -- Grammar Summary.md Outdated

Comment thread spec/Section 3 -- Type System.md Outdated

Comment thread spec/Section 3 -- Type System.md Outdated

Comment thread spec/Section 3 -- Type System.md Outdated

leebyron and others added 2 commits August 31, 2025 22:10

Apply suggestions from code review

3a9e537

Co-authored-by: Benjie <benjie@jemjie.com>

move and minor edits

c41e64f

leebyron force-pushed the schema_coordinates_spec_edit branch from 1347a1e to c41e64f Compare September 1, 2025 05:41

tighten notes

580d292

leebyron force-pushed the schema_coordinates_spec_edit branch from 1a71923 to 580d292 Compare September 1, 2025 05:47

update resolution grammar

959fe1b

leebyron force-pushed the schema_coordinates_spec_edit branch from 12c7bfc to 959fe1b Compare September 1, 2025 05:49

fix table style

6d3e3f0

leebyron merged commit 1e29b8a into graphql:main Sep 1, 2025
9 checks passed

tyranron mentioned this pull request Sep 8, 2025

GraphQL spec September 2025 graphql-rust/juniper#1347

Open

23 tasks

This was referenced Apr 14, 2026

Allow executable document comments graph-gophers/graphql-go#725

Closed

Schema Coordinates graph-gophers/graphql-go#726

Open

		Schema Coordinates are always unique. Each type, field, argument, enum value, or
		directive may be referenced by exactly one possible Schema Coordinate.

Conversation

magicmark commented Nov 18, 2020 • edited by benjie Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

magicmark commented Nov 18, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

magicmark Jan 4, 2021

Choose a reason for hiding this comment

Uh oh!

magicmark Jan 4, 2021

Choose a reason for hiding this comment

Uh oh!

magicmark Jan 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie Jan 5, 2021

Choose a reason for hiding this comment

Uh oh!

magicmark Jan 7, 2021

Choose a reason for hiding this comment

Uh oh!

mcohen75 commented Feb 4, 2021

Uh oh!

leebyron commented Apr 14, 2021

Uh oh!

leebyron commented Apr 14, 2021

Uh oh!

Uh oh!

benjie commented Jul 4, 2025

Uh oh!

magicmark commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

magicmark commented Aug 7, 2025

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjie commented Aug 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

magicmark commented Nov 18, 2020 •

edited by benjie

Loading

magicmark commented Nov 18, 2020 •

edited

Loading

magicmark Jan 4, 2021 •

edited

Loading

magicmark commented Jul 4, 2025 •

edited

Loading