Skip to content
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

Open
magicmark opened this issue Jun 15, 2020 · 7 comments
Open

Standardize naming for "Schema Coordinates" (e.g. Foo.bar) #735

magicmark opened this issue Jun 15, 2020 · 7 comments

Comments

@magicmark
Copy link
Contributor

magicmark commented Jun 15, 2020

Update: RFC PR is here! #746


For example, given this schema:

type Business {
    reviews: [Reviews]
    name: String
}

type Review {
    body: String
    ...
}
  • Business.name uniquely identifies the "name" field on the "Business" type
  • Business.reviews uniquely identifies the "reviews" field on the "Business" type
  • Review.body uniquely identifies the "body" field on the "Review" type

We 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!

@magicmark magicmark changed the title Standardize naming for "type/field pairs"? Standardize naming for "type/field pairs" (Foo.bar)? Jun 15, 2020
@magicmark magicmark changed the title Standardize naming for "type/field pairs" (Foo.bar)? Standardize naming for "type/field pairs" (e.g. Foo.bar)? Jun 15, 2020
@IvanGoncharov IvanGoncharov added the 💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md) label Jun 15, 2020
@benjie
Copy link
Member

benjie commented Jun 16, 2020

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):

  • Foo::bar
  • Foo#bar
  • Foo->bar
  • Foo~bar
  • Foo:bar

One advantage of Foo.bar is that it's already used in GraphiQL and thus effectively already the standard, and that may be sufficient to make it the official way.

@andimarek
Copy link
Contributor

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.

@magicmark
Copy link
Contributor Author

magicmark commented Jul 3, 2020

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 Foo.bar to be consistent with existing tooling (also fits my mental model of accessing a property on an object) - but totally happy to be outvoted here. (Also if it conflicts with other langauge proposals, that would be a good reason to change it.)

@craigsmitham
Copy link

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.

@xuorig
Copy link
Member

xuorig commented Jul 8, 2020

We use the Foo.bar notation at GitHub and GraphQL-Ruby has been supporting a similar syntax for a while

@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: Product.fields[@type = "Boolean"].

@magicmark magicmark changed the title Standardize naming for "type/field pairs" (e.g. Foo.bar)? Standardize naming for "Field coordinates" (e.g. Foo.bar)? Jul 8, 2020
magicmark added a commit to magicmark/graphql-wg that referenced this issue Aug 1, 2020
👋 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!
leebyron added a commit to graphql/graphql-wg that referenced this issue Aug 5, 2020
👋 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>
@leebyron leebyron added 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) and removed 💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md) labels Aug 6, 2020
@n1ru4l
Copy link

n1ru4l commented Sep 17, 2020

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. Query.post), which will then re-execute all operations that select Query.post. However, that might not be granular enough for some use-cases. E.g. if the post field accepts an id argument, only queries that select Query.post with the matching argument id should be re-executed.

I have already thought about something like Query.post(id:"1"). Instead of :, = could also be used. I am not sure about more complex argument types e.g. objects. For those probably an encoded JSON like formatting would fit, the arguments might then also be alphabetically ordered? E.g. Query.post(id:{a:"1",b:1}).

Is this something that would be part of this RFC or is the scope rather to only uniquely identify field (arguments)? E.g. Query.post(id)?

@magicmark magicmark changed the title Standardize naming for "Field coordinates" (e.g. Foo.bar)? Standardize naming for "Schema Selectors" (e.g. Foo.bar) Oct 7, 2020
@magicmark magicmark changed the title Standardize naming for "Schema Selectors" (e.g. Foo.bar) Standardize naming for "Schema Coordinates" (e.g. Foo.bar) Nov 3, 2020
brucelongmore28 added a commit to brucelongmore28/graphql-wg-membership-note that referenced this issue Dec 1, 2022
👋 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>
@benjie benjie removed the 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) label Jan 20, 2023
@benjie
Copy link
Member

benjie commented Jan 20, 2023

Removing the RFC status from this because it's confusing/out of date - this is actually RFC2 in #794

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

8 participants