Schema Coordinates

[magicmark]

👋

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]

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]

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

[magicmark]

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

[magicmark]

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!

[benjie]

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.

[magicmark]

👍 thanks benjie, stealing this wording

[mcohen75]

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]

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]

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

[benjie]

There has been discussion around whether having the coordinate for a field and an enum value be the same makes sense. I propose that we change the syntax used for enum values from . to :::

Type # Any named type
Type.field # A field (e.g. on an object, interface, or inputObject type)
Type.field(argName:) # An argument (on an object or interface type)
Type::value # an Enum value (on an enum type)

:: is the syntax used to reference an enum value in C++, Rust, PHP, Perl and others, so it seems pretty natural.

I also think that doing this will make it more obvious for users reading a schema coordinate that it's an enum value being referenced rather than a field (and vice versa).

[benjie]

I have raised a PR to implement these changes here: magicmark#1

[benjie]

Everyone who has previously approved this PR should re-approve it with the new Type::VALUE syntax for enum values.

[martinbonnin]

Looks great!

Just left a few unimportant nitpicks.
My main question is still around meta fields. I still think we should include them for consistency, simplicity and also because I want to monitor usage of meta fields as well.

[PascalSenn]

In my opinion, using :: introduces several issues:

• While this is still a proposal, schema coordinates are already an established part of the GraphQL ecosystem. Changing the format at this stage would require all existing GraphQL servers that have implemented the proposal to update their parsers, add backward compatibility for the old format, and potentially modify all related tooling. Tools that rely on schema coordinates to identify schema elements may break, need migration paths, or require compatibility layers.

• If we decide to support union member coordinates in the future, the appropriate delimiter becomes ambiguous. Should it be Foo.Bar, Foo::Bar, or Foo->Bar?

• From my perspective ( influenced by JS, TS, and C#), Foo.BAR naturally points to an enum member. In contrast, Foo::BAR feels less intuitive.

• When looking up schema members via a schema coordinate, the choice of separator is irrelevant - both represent the same concept. Tooling on the other hand will likely require additional context anyway, since, for example, an input field differs fundamentally from an output field. So, do we really need a different separator? (@, Type, Member, Arg)

[benjie]

Conclusion from the WG was to:

a) support meta fields
b) use the same syntax for fields and enum values.

Sorry @JoviDeCroock, you were outvoted! I think your concerns have merit and hopefully I represented them well, but equally what we're primarily doing here is encoding a pattern we already see in the ecosystem and apparently people are actively encoding enum values like this (who knew? I only ever see schema coordinates used for types, fields, arguments and directives!) so "member" it is! 🤷

[benjie]

I didn't voice it during the call because we were already over time, but there are legitimate reasons why enum values might not always be CONSTANT_CASE; for example if you wish to allow filtering of an abstract type to only certain types you might do e.g.{ user { pets(only: [Cat, Dog]) { name } } } where Cat and Dog are enum values that exactly match the type names used in the schema (this is more obvious when the type names are formed of multiple words). There are other scenarios where CONSTANT_CASE is not a perfect fit, but I certainly agree that it should be the default for most things unless you have a very good reason.

[magicmark]

Updates June 6th 2025:

• I have reverted back to proposing MemberCoordinates (Name.Name) to refer to both object fields and enum values, per the WG discussion and reasoning above.
• meta-fields are no longer disallowed (@leebyron doesn't remember why we added this restriction in the first place)
• union members are still disallowed. I don't have super strong opinions for if we should allow that or not (I personally can't think of use cases we would have for that), but either way, my strong preference would be to tackle this in a future spec proposal should we decide to add support for that.

Implementation changes here: graphql/graphql-js#4432