[RFC] Add directives to field definitions

[fson]

This proposal extends the GraphQL IDL syntax to support directives for fields in types. Directives can be used to add custom metadata / annotations to fields.

Being able to add tool specific metadata to fields opens up new possibilities for tools that use the GraphQL IDL to bootstrap the schema. For example, we are planning to use the definition language for specifying a schema in our GraphQL BaaS and doing so requires a way to add metadata to fields. E.g. to create a relationship between types, a @connection directive could be used like this:

type TvSeason implements Node {
  @connection(relatedField: "season")
  episodes: TvEpisodeConnection
  id: ID!
}

[leebyron]

Thanks for proposing this, @fson!

The one primary concern I have is the inconsistency of placement of the directive. With this extension, this will be likely interpreted differently by a human and the parser:

type T {
  a: A @meta(data: "foo")
  b: B
}

I think most will assume a post-fix placement based on how directives are used in the queries.

I'm curious what your opinion is of a meta-data-in-comments style solution? I know they're controversial in other languages since comments should probably just be comments. But they can have nice and clear dev ergonomics:

type TvSeason implements Node {

  # Description for the episodes field could just live in a comment
  # followed by meta-data...
  # @connectionRelatedField: season
  episodes: TvEpisodeConnection

  id: ID!

}

[leebyron]

Another aspect of this to consider is how this metadata might be exposed via introspection. One of our goals is for this IDL to be fully constructable from a full introspection query and vice versa.

[fson]

Thanks for your comments @leebyron!

The inconsistency of placement is a valid concern. I used then same placement as query directives have at first, but wanted to try this prefix placement because I think it's more familiar to people who have worked with JavaScript or Java classes for example. However I can see now that the inconsistency with the query directives would likely be more confusing and postfix placement would probably be better.

[fson]

@leebyron I think writing descriptions as comments is an interesting idea and I like your example, looks nice and uncluttered.

Embedding metadata in the comments would mean they essentially become a part of the description. This solves the introspection problem you mentioned.

A potential downside of this is that descriptions are expected to be just markdown, so the annotations wouldn't be rendered nicely in tools like GraphiQL, unless we define some simple grammar for them. For Reindex this would not be a problem since we use the user defined schema as input and generate the final schema with input objects, mutations etc. based on it. We could simply strip the annotations from the descriptions in the resulting schema.

[jontonsoup]

@fson I'm wondering if you have a solution you could point me to that allows for custom metadata to be stored in a schema and can be queried through introspection (Seems to be the point of this PR?). It would be super helpful for something I'm working on :)

[fson]

@jontonsoup I don't think such mechanism exists at the moment. In Reindex we currently use a JSON based schema definition to describe the types and then generate the GraphQL schema (automatically adding connections, input objects etc). In our use case there's no need to preserve the metadata in the final schema, which will be no different than if it was authored in JS by hand.

However, GraphQL IDL would in my opinion be a more developer friendly way to author the initial schema definition, which is what we would need the metadata for.

[jontonsoup]

@fson Thanks!

[igorcanadi]

LOL, I haven't seen this PR at all, I made almost identical PR here: #264 . I'm implementing support in extendSchema() and will also try to address the introspection issue raised by @leebyron.

[fson]

@igorcanadi Cool! I'm closing this now in favor of your PR, since it's more complete, for example it adds the directives to the visitors and printer.