Schema Coordinates #794

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!

spec/Appendix C -- Schema Coordinates.md

spec/Section 3 -- Type System.md

benjie

Looks good to me; a few optional tweaks suggested.

spec/Section 3 -- Type System.md

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

spec/Section 3 -- Type System.md

+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

spec/Section 3 -- Type System.md

+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?

…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

spec/Appendix B -- Grammar Summary.md

spec/Section 3 -- Type System.md

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 <[email protected]>

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 <[email protected]> Co-authored-by: Mark Larah <[email protected]> Co-authored-by: Yaacov Rydzinski <[email protected]>

…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 <[email protected]>

…QLEnumValue (#4288) this extracts logic from #3044 and #3145 (later rebased as #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 <[email protected]>

magicmark mentioned this pull request Nov 18, 2020

RFC: Schema Coordinates #746

Merged

benjie requested changes Nov 18, 2020

View reviewed changes

spec/Appendix C -- Schema Coordinates.md Outdated Show resolved Hide resolved

spec/Appendix C -- Schema Coordinates.md Outdated Show resolved Hide resolved

leebyron reviewed Nov 19, 2020

View reviewed changes

spec/Appendix C -- Schema Coordinates.md Outdated Show resolved Hide resolved

spec/Appendix C -- Schema Coordinates.md Outdated Show resolved Hide resolved

spec/Appendix C -- Schema Coordinates.md Outdated Show resolved Hide resolved

magicmark commented Nov 21, 2020

View reviewed changes

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

benjie approved these changes Nov 23, 2020

View reviewed changes

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

leebyron reviewed Dec 3, 2020

View reviewed changes

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

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

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

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

Apply suggestions from code review

3a9e537

Co-authored-by: Benjie <[email protected]>

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

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

Schema Coordinates #794

Schema Coordinates #794

Uh oh!

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!

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