-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Standardize naming for "Schema Coordinates" (e.g. Foo.bar
)
#735
Comments
Foo.bar
)?
Foo.bar
)?Foo.bar
)?
I agree with the drive for this. However, bikeshedding, we need to ensure that it wouldn't conflict with features we might add in future, such as namespaces. Of course we could just choose a different symbol for these relevant features, but the dot is particularly convenient. Alternative symbol choices that might be suitable for type/field pair (or other features):
One advantage of |
As a meta comment: I think helping to communicate GraphQL concepts across ecosystems and implementation is a core responsibility of the GraphQL spec. Therefore standardizing this concept by giving it a clear name is a good goal. In GraphQL Java for example we call it "Field coordinates" and we print it as "Foo:bar". In another project the notation "Foo.bar" is used. |
Thanks for the feedback! Ooh, I like "field coordinates", that's slightly more descriptive and less awkward than "type/field pair". Not 100% sure on the process here, but I'll send a PR to amend the spec with a little paragraph about this, and we can move the discussion there. I'll vote to keep |
Something else to consider is being able to notate arguments as well. For example, an argument named “baz” on object field Foo.bar: “Foo.bar.baz”. This is the approach I’m taking to concisely refer to schema elements in error messages. If it’s always paired with the name of the element referred to: “object field argument Foo.bar.baz”. I’m not sure what I would call this from a spec perspective, what do we call the elements of a schema? Members, elements? Then it would be a member or element path. “Pair” only gives you a path length of two. “Path” is a little more fitting. I’m a fan of dot notation as it’s familiar and the least surprising/confusing. Whatever the notation, it will most likely always be paired with the type of the element (e.g. “object field”, “directive argument”, “interface field argument”, etc). So, something as simple as for notation makes sense for reasons other comments have articulated. I do think a special delimiter besides a dot between the namespace and the member path would probably make sense. |
We use the @dschafer mentioned they were using a similar approach at FB: https://twitter.com/__xuorig__/status/1223344851778928652 A GraphQL-Path RFC in general would be really useful for tooling to refer to specific schema members. I can even see filters eventually being useful for certain tools: |
Foo.bar
)?Foo.bar
)?
👋 hi! Would love to get some discussion going on graphql/graphql-spec#735 / graphql/graphql-spec#746 so I can figure out what (or rather "if") what the next steps might be thanks!
👋 hi! Would love to get some discussion going on graphql/graphql-spec#735 / graphql/graphql-spec#746 so I can figure out what (or rather "if") what the next steps might be thanks! Co-authored-by: Lee Byron <lee@leebyron.com>
Hey there, I just watched parts of the Working Group August video recording on YouTube and wanted to mention my use case for also having arguments encoded inside the field coordinates. I am building a live query engine that re-executes an operation and publishes it to the client. Currently, the execution is scheduled by publishing a field coordinate string (e.g. I have already thought about something like Is this something that would be part of this RFC or is the scope rather to only uniquely identify field (arguments)? E.g. |
Foo.bar
)?Foo.bar
)
Foo.bar
)Foo.bar
)
👋 hi! Would love to get some discussion going on graphql/graphql-spec#735 / graphql/graphql-spec#746 so I can figure out what (or rather "if") what the next steps might be thanks! Co-authored-by: Lee Byron <lee@leebyron.com>
Removing the RFC status from this because it's confusing/out of date - this is actually RFC2 in #794 |
Update: RFC PR is here! #746
For example, given this schema:
Business.name
uniquely identifies the "name" field on the "Business" typeBusiness.reviews
uniquely identifies the "reviews" field on the "Business" typeReview.body
uniquely identifies the "body" field on the "Review" typeWe intuitively understand what this dot separated string means, but I can't find anything anywhere that formalizes its definition, or what it's even called.
I'll go with "type/field pair" for now since I vaguely remember seeing that somewhere (but can't remember where)Why do we want this?
Various tooling wants to show field coordinates - usually for documentation or metrics/tracking purposes.
Examples:
GraphiQL's documentation tab search bar showing field coordinates to uniquely identify fields:
GraphQL Inspector (840 stars) displays field coordinates in its output:
And internally at Yelp, we want to show a list of "most popular fields in the schema" - using field coordinates is a good way to track this!
The ask
Being able to communicate what this strange dot separated string means would be useful to folks onboarding, and it'd be great to standardize this and point to something in the spec/official docs.
Does this worth standardizing and including in the docs?
Thanks!
The text was updated successfully, but these errors were encountered: