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!

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?

- Make examples table - Tweak the grammar definition

- move schema coordinates to section 3.3.3 - add lee's grammar suggestion

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

- remove extraneous examples - tighten up wording

https://brians.wsu.edu/2016/05/31/standalone-stand-alone/ Co-authored-by: Benjie Gillam <[email protected]>

netlify · 2024-12-10T17:16:09Z

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	`d61cdc3`
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/67587f186771b30008b11945
😎 Deploy Preview	https://deploy-preview-794--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

cheapsteak · 2024-12-10T21:31:08Z

@magicmark

@cheapsteak do you have an example syntax for what you had in mind? If i'm understanding correctly

yup for sure 🙏

e.g. using Yelp's schema, something like Business.id~description to address the description of the field, or Business~description to address the description of the type, or Business.id~returnType to address the return type of the field

Our use case is allowing users to comment on a particular part of a schema, and while we can dangle them off of the type or field, it's not really the right place

benjie · 2024-12-11T10:18:47Z

Alternative syntax: Business.id#description inspired by Ruby/PHP/Elixir.

If we want to explore this, we should explore it further:

Animal#description
Animal#members
Animal#members#Cat -- Not currently useful?
Animal#members#Cat#deprecationReason -- Not currently possible to deprecate union members
Animal#members#Cat#description -- Not currently possible: union members can't currently have descriptions. Note: NOT the same as Cat#description.
Cat#description
Cat#deprecationReason
Cat.lives#description
Cat.lives#deprecationReason
Cat.lives#type
Cat.lives(includingSpent:)#type
Cat.lives(includingSpent:)#description
Cat.lives(includingSpent:)#deprecationReason
MyEnum#description
MyEnum#deprecationReason
MyEnum.MY_VALUE#description
MyEnum.MY_VALUE#deprecationReason

Technically until we have #300 or similar we can't represent arbitrary directives on a position, but arguably we should consider that too:

MyEnum.MY_VALUE@myDirective{3}(arg:) < the arg argument on the third myDirective (repeatable) directive applied to the MY_VALUE type on the MyEnum enum. 😅

cheapsteak · 2024-12-11T15:03:40Z

@benjie that all looks great! 🙏 although one nit with # is that it's not url safe and would need to be escaped

benjie · 2024-12-11T17:40:18Z

Sadly same is true already of : - though most browsers can handle it unescaped, if you put it through encodeURIComponent it will be escaped:

> encodeURIComponent(':')
'%3A'
> new URLSearchParams({a: ':'}).toString()
'a=%3A'

magicmark · 2024-12-12T15:58:30Z

thanks @cheapsteak!

I understand the use case now, makes sense.

at this point, things are pretty stable and we've already had many rounds of discussions on the syntax of this spec to reach alignment. it looks like we're near to being able to close this out.

so the question is, do we want to try and expand the scope of this rfc and re-open it up, or follow it up with another rfc?

my preference would be the latter - there are already discussions around expanding this spec in future (https://github.com/graphql/graphql-wg/blob/main/rfcs/OperationExpressions.md) so I think amending this spec as a separate RFC (which could be opened now) would make most sense to allow us to move forward on these proposals independently. (curious what @benjie thinks on this strategy)

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 benjie and a team 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

magicmark and others added 19 commits December 10, 2024 11:08

Update schema coordinates spec edit

45fb46c

- Make examples table - Tweak the grammar definition

implement PR suggestions

eabdaff

- move schema coordinates to section 3.3.3 - add lee's grammar suggestion

Tweak example table wording

f994f99

Apply suggestions from code review

17002d4

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

enumName -> enumValueName

6456c5f

- Add PR feedback

4905977

- remove extraneous examples - tighten up wording

Update Section 3 -- Type System.md

8be29ca

Editorial on grammar and semantics

568d26f

Move section

b8f3f47

Simplify examples

8580162

standalone

87a38e2

https://brians.wsu.edu/2016/05/31/standalone-stand-alone/ Co-authored-by: Benjie Gillam <[email protected]>

update numbers

75c48ba

clarify element

148d073

Update Punctuator grammar

c43f4aa

specify schema element

bb896cf

fix example

e5a2092

clarify metafields

b65eb31

Better Punctator

c16a28b

Minor algo variable name refinements

93bd2c6

magicmark force-pushed the schema_coordinates_spec_edit branch from e6f7939 to 93bd2c6 Compare December 10, 2024 17:15

magicmark added 4 commits December 10, 2024 11:17

whitespace fix

b2e42e8

add note about union members

4ce2d48

prettier

2d60b33

formatting

d61cdc3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Schema Coordinates #794

Schema Coordinates #794

magicmark commented Nov 18, 2020

magicmark commented Nov 18, 2020 •

edited

Loading

benjie left a comment

benjie left a comment

magicmark Jan 4, 2021

magicmark Jan 4, 2021

magicmark Jan 4, 2021 •

edited

Loading

benjie Jan 5, 2021

magicmark Jan 7, 2021

mcohen75 commented Feb 4, 2021

leebyron commented Apr 14, 2021

leebyron commented Apr 14, 2021

netlify bot commented Dec 10, 2024 •

edited

Loading

cheapsteak commented Dec 10, 2024

benjie commented Dec 11, 2024 •

edited

Loading

cheapsteak commented Dec 11, 2024

benjie commented Dec 11, 2024

magicmark commented Dec 12, 2024 •

edited

Loading

		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

Are you sure you want to change the base?

Schema Coordinates #794

Conversation

magicmark commented Nov 18, 2020

magicmark commented Nov 18, 2020 • edited Loading

benjie left a comment

Choose a reason for hiding this comment

benjie left a comment

Choose a reason for hiding this comment

magicmark Jan 4, 2021

Choose a reason for hiding this comment

magicmark Jan 4, 2021

Choose a reason for hiding this comment

magicmark Jan 4, 2021 • edited Loading

Choose a reason for hiding this comment

benjie Jan 5, 2021

Choose a reason for hiding this comment

magicmark Jan 7, 2021

Choose a reason for hiding this comment

mcohen75 commented Feb 4, 2021

leebyron commented Apr 14, 2021

leebyron commented Apr 14, 2021

netlify bot commented Dec 10, 2024 • edited Loading

✅ Deploy Preview for graphql-spec-draft ready!

cheapsteak commented Dec 10, 2024

benjie commented Dec 11, 2024 • edited Loading

cheapsteak commented Dec 11, 2024

benjie commented Dec 11, 2024

magicmark commented Dec 12, 2024 • edited Loading

magicmark commented Nov 18, 2020 •

edited

Loading

magicmark Jan 4, 2021 •

edited

Loading

netlify bot commented Dec 10, 2024 •

edited

Loading

benjie commented Dec 11, 2024 •

edited

Loading

magicmark commented Dec 12, 2024 •

edited

Loading