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

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

[benjie]

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]

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]

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]

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]

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