Skip to content

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

Closed

Description

@magicmark

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!

Activity

  1. changed the title [-]Standardize naming for "type/field pairs"?[/-] [+]Standardize naming for "type/field pairs" (`Foo.bar`)?[/+] on Jun 15, 2020
  2. changed the title [-]Standardize naming for "type/field pairs" (`Foo.bar`)?[/-] [+]Standardize naming for "type/field pairs" (e.g. `Foo.bar`)?[/+] on Jun 15, 2020
  3. benjie commented on Jun 16, 2020

    @benjie
    Member

    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.

  4. andimarek commented on Jun 20, 2020

    @andimarek
    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.

  5. magicmark commented on Jul 3, 2020

    @magicmark
    ContributorAuthor

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

  6. craigsmitham commented on Jul 3, 2020

    @craigsmitham

    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.

  7. xuorig commented on Jul 8, 2020

    @xuorig
    Member

    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"].

  8. changed the title [-]Standardize naming for "type/field pairs" (e.g. `Foo.bar`)?[/-] [+]Standardize naming for "Field coordinates" (e.g. `Foo.bar`)?[/+] on Jul 8, 2020
  9. n1ru4l commented on Sep 17, 2020

    @n1ru4l

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

  10. changed the title [-]Standardize naming for "Field coordinates" (e.g. `Foo.bar`)?[/-] [+]Standardize naming for "Schema Selectors" (e.g. `Foo.bar`)[/+] on Oct 7, 2020
  11. changed the title [-]Standardize naming for "Schema Selectors" (e.g. `Foo.bar`)[/-] [+]Standardize naming for "Schema Coordinates" (e.g. `Foo.bar`)[/+] on Nov 3, 2020
  12. benjie commented on Jan 20, 2023

    @benjie
    Member

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

  13. added
    💤 stale ?This issue/PR has not been updated in more than 1 year and is not actionable anymore.
    on Mar 5, 2026
  14. removed
    💤 stale ?This issue/PR has not been updated in more than 1 year and is not actionable anymore.
    on Mar 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions