Support for defining metadata on graphql types

[aschrijver]

It would be nice if the specification defined a standard way to define metadata in a schema definition for individual types, interfaces, fields, etc. This would not be query metadata, like you have with directives, but e.g. server implementation specific metadata, or whatever an implementer needs to model additional logic on top of a schema. In other words a general metadata extension mechanism.

I described this in more detail and with examples on the graphql-java project in this issue: https://github.com/graphql-java/graphql-java/issues/183

Maybe the metadata mechanism could be implemented using an additional introspection type __METADATA or something similar.

WDYT?

[OlegIlyenko]

I think it's a interesting idea. Especially now that schema definition language (IDL) supports directives as well. This information is not exposed to a client via introspection API and, at the moment, only part of the AST.

In sangria (scala implementation), for instance, there is a concept of FieldTags which allows user to attach additional meta-information to a an ObjectType fields. This meta-information can be used in middleware or query reducers to provide more application-specific information about the fields. But this meta-information is not exposed to a client in any way either.

I find that it can beneficial to expose this application-specific meta-information to a client via introspection API. Maybe it can be exposed in a form of directives? For example a __Type can have a filed called directives and it will expose a list of directives (these are not directive definitions, like in top-level field, but rather an actual directive application).

I think it would be helpful if you could list a few use-cases that demonstrate how client can benefit from using this meta-information exposed via introspection API.

[aschrijver]

Yes I can. First of all I think it is important to see that the 'client' is much more than client-side javascript that executes queries against a HTTP GraphQL endpoint (as you usually encounter it). It has been stated that GraphQL is ideal in a microservices environment. And it is. In these kind of applications queries may cross many boundaries and use many different transports. So you can have multiple clients (and publishers) in one execution chain. Metadata can be used here for infrastructure support and configuration settings, for example.

In my own use case for vertx-graphql-schema-proxy and vertx-graphql-service-discovery I want to use it for marshalling settings and to determine the point from which a query is no longer allowed to execute on the proxy client, but should be deferred to the backend.

[aschrijver]

Its not only these more environment-specific metadata that could be relevant, but you could also use it to add much more descriptive information on the type definition itself. Think of a category, list of keywords, access modifiers, RDF descriptors, documentation links, related types, localization data, etc.

[aschrijver]

Oh. Almost forgot to mention. The __METADATA can be used to define expected metadata formats just like you have for types.

[aschrijver]

See also the discussion on GraphQL Java project for adding metadata. I added additional use cases: https://github.com/graphql-java/graphql-java/issues/183 and my comment here https://github.com/facebook/graphql/issues/163#issuecomment-236462251 The issue has been closed because there is nothing similar in graphql-js and graphql-java is following that as a reference implementation.

@leebyron I would be quite interested in your views on this topic.

[taion]

I believe this is essentially a dupe of https://github.com/facebook/graphql/issues/300, which has more discussion, and as such should be closed out.

[aschrijver]

thanks @taion closing in favour of #300

[wtrocki]

See: https://github.com/aerogear/graphql-metadata