"Metadata Directives" Proposal

[leebyron]

Given the revived discussion around schema metadata and their relationship with SDL directives, I'd like to propose a high level direction for this. My goal here is to introduce something with as few additional moving parts as possible. It's intended to be simple rather than robust.

The primary new mechanism is being able to mark an SDL Directive definition as metadata and exposing such directive usages via introspection. Given an introspection result you should be able to re-create the SDL with directive usages in the right places.

The main downside is that the introspection encoding is simple to the point of requiring post-processing. There is no explicit sub-selection; all metadata gets exposed in introspection. The metadata is not in a structured JSON form, but in arrays of named groups - however this more clearly maps to the way directives are being used. It's up to tools consuming metadata to interpret these as intended.

I'd love feedback on this!

# An SDL directive can now be marked as `metadata`, mirroring how it can be 
# marked as `repeatable`. Doing so causes usages of it within a schema to be 
# visible via introspection.

directive @myCustomMetadata(myValue: String) metadata repeatable on FIELD

# This appears in introspection as well. `__Directive` gains an `isMetadata` 
# field, again mirroring the existing `isRepeatable` field.

type __Directive {
  # ...
  isMetadata: Boolean
}

# Once a directive is marked as a "metadata" directive, then usages of it appear
# as metadata at that location in the schema.
#
# Schema introspection types all get a `metadata` field, of type `[__Metadata]`.
# This allows multiple pieces of metadata per location in an introspected schema.
#
# As `metadata` is a list, this allows for retaining their order (which spec 
# preserves as potentially meaningful) as well as repeated directives.
#
# No changes are needed to SDL, since we're using existing directive syntax.

type __Field {
  # ...
  metadata: [__Metadata!] # Example of this being added to all things.
}

# The `__Metadata` type models a single metadata directive usage at a location.
# Therefore it both refers to the directive definition being used, as well as
# the values being used.
#
# Note that `values` could be null in the case of a directive usage without args
# ex: `{ myField @myDirective }`. Also note that since `values` is a list, that
# the order of the directive arguments can be preserved.

type __Metadata {
  """
  Additional information provided for an item in a GraphQL schema.
  """

  directive: __Directive!
  values: [__MetadataValue!]
}

# A `__MetadataValue` is very similar to the existing `__InputValue`. However,
# as it represents a provided value instead of a definition of a value, only the 
# `name` and `value` fields are relevant.
#
# Similar to `defaultValue` in `__InputValue`, the `value` argument is a String 
# encoding using the GraphQL language. This allows all varities of values which
# can be modeled as a GraphQL value. Tools may prefer to convert this to JSON 
# after fetching.

type __MetadataValue {
  name: String!
  value: String!
}

That's it! Let's take a look at an example:

# For this type's `myField` field, a metadata directive is used with a value provided.

type MyType {
  myField: Int @myCustomMetadata(myValue: "some value")
}

# Given a typical introspection query, here's some additional fields queried on 
# field during introspection:

fragment FieldMetadata on __Field {
  metadata {
    directive { name }
    values {
      name
      value
    }
  }
}

And here's the resulting introspection response (in JSON5) for this particular fragment applying to the myField

{
  name: "myField",
  // ....
  metadata: [
    {
      directive: { name: "myCustomMetadata" },
      values: [
        { 
          name: "myValue",
          value: "\"some value\"" // Note GraphQL encoding.
        }
      ]
    }
  ]
}

[rivantsov]

Well, looks good. I would like to make a few re-naming suggestions. The __Metadata type:

type __Metadata {
   directive: __Directive!
   values: [__MetadataValue!]
}

type __MetadataValue {
  name: String!
  value: String!
}

What we have here is ref to Directive, and its arg values - I think AppliedDirective would be more intuitive:

type __AppliedDirective {
   directive: __Directive!
   values: [__ArgValue!]
}
type __ArgValue {
  name: String!
  value: String!
}

And on introspection types, I suggest the field name for AppliedDirectives:

type __Field {
  # ...
  appliedDirectives: [__AppliedDirective!] # instead of 'metadata'
}

Previously, I suggested to move away from the term 'custom metadata'; in this post I explain why;
scroll down to section "Is it really custom meta-data we are talking about?". So I suggest a switch from 'metadata' to 'AppliedDirective'.
And it looks like the other Custom Metadata group also decided to switch from 'metadata' to 'annotations':
#1069 (comment)

Now, wait a minute - what we have here now, with this renaming is the appliedDirectives approach that I am arguing for! Seriously, I am happy that you came up with practically the same thing. Let's push for this approach together!

I will follow up with some other comments regarding few other aspects in your suggestion.
Have a nice weekend!

[leebyron]

Happy to hear that most feedback is about naming! My hope is that the structure of this approach is something we might build consensus around. I'm happy to bike-shed on naming.

My qualms with "applied directive" in the past is that it leaves some ambiguity about any directives applied which are not publicly exposed (currently, before any of these proposals: all of them). I wonder if naming it something that aligns to the "this is public" marker and the intent would be easier to understand.

[bbakerman]

Naming is hard - lets go shopping - but for me the metadata didnt ring clear as a name.

In the current graphql-java implementation (that optional exposes directives in introspection) we chose "Applied Directives" as a name to 1) be consistent with Hot Chocolate who already had a mechanism named like this and 2) because the directives are "applied" to schema elements in SDL as opposed to declared as a possible directive.

I could live with __Metadata as a name if need be - BUT there are already two popular graphql implementations that have used AppliedDirective in a consistent way and hence that should add some weight to that as alternative naming.

I am happy with the shape of directive arguments and values (naming aside). I think graphql encoding is the way forward because its 1) consistent with what exists and that is a powerful thing and 2) the alternative is a Any | Json type for values and I dont think that is more useful in effect.

I agree with the public | private marker on the directive definition to decide if its to be placed in introspection.

In our graphql implementation at Atlassian we have directives that are used to indicate behaviors to the implementation but which are not exposed (say oauth scope names to check) and we have others that are used to indicate behaviors to the implementation AND are designed to be exposed in introspection to other tooling (api groupings for documentation purposes)

I say this to add weight to the idea that there are directives you want to be introspectable and ones that you do not, hence the need for the attribute on the directive definition to indicate if they should be exposed.

Perhaps another name of this is introspectable

directive @myCustomMetadata(myValue: String) introspectable repeatable on FIELD

[michaelstaib]

When we implemented the Applied Directive concept with Hot Chocolate we added an internal switch to the directive allowing the user to expose them or not... essentially we modeled that as a modifier that could have the value public or internal. This is essentially what the metadata keyword is doing now.

There is still one downside in the overall design here, which exists any way for input fields, and that is that values still need to be parsed twice... essentially the result must be parsed, and in a second round, the values must be parsed.

I do not think that is necessarily an issue we need to solve since this issue already exists with the default value, but it's good to point it out and reflect on it.

The things I like about this approach and the applied directives approach are that it is a minimal change to unlock metadata and many use-cases with it. In general, we should try to unlock features like this with an incremental change rather than with a big leap, as they allow for faster iteration and fewer risks to current implementations.

In general, I think that we should take directives and improve them rather than introducing something new here. Regarding the naming, if we distinguish certain kinds of directives as metadata, then we should also use that in the introspection as applied directive would indicate that I can access all applied directives, which is not the case. So, I am in favor of the __Metadata type name.

[leebyron]

There is still one downside in the overall design here, which exists any way for input fields, and that is that values still need to be parsed twice... essentially the result must be parsed, and in a second round, the values must be parsed.

This is certainly a downside, but it may be necessary to leave this to tools. Just about all tools need to do some post-processing on introspection results anyhow, so "requires a second step" seems pretty close to status quo.

I'm not sure how possible it is to offer it in any other form. Custom scalars and Enums in particular make a translation to JSON potentially lossy, and since introspection of these offers a reference to the __Directive type they are provided through, then all of the types necessary to interpret them.

But I still don't like how much this leaves to tools to misinterpret. We could define how this gets translated back into a structured data (i.e. JSON) response, but I think it would be the only place we convert in that way.

See this diagram I made last year about the forms of data flowing through

[leebyron]

The shallow argument for the double-encoded values is that defaultValue in introspection does the same. The diagram there was made last year when untangling some particular challenging bugs around exactly that encoding.

The introduction of a Literal to Value near the top center as the reverse of the existing Value to Literal would make this possible.

Part of the original motivation for the double-encoded defaultValue was to differentiate between null as the absence of a default value and "null" as the encoded null literal default value. We don't have that same problem here.

[leebyron]

The other part of the motivation is that this would be an otherwise untyped Any, which we've tried to avoid up until this point.

I appreciate that this is part of the intent behind STRUCT metadata - to introduce such types and avoid Any, but I do worry about the cascade of types this produces in introspection.

I wonder if we should tie together the desire to avoid encoding data this way with a need for an Any type. I'm sure @benjie has opinions about this :)

[michaelstaib]

The main argument against Any here is that it's untyped, although it's typed.

I mean, tooling could work around this and infer the typings for this.

Also, I would like to avoid tying features to other features since this quickly clogs the process since we are waiting for something that does not exist, and we project some characteristics it should have, but that might change.

I mean, the suggestion that @rivantsov made is not bad that we could always introduce a projection of the value. Like we could go with value for now, which is GraphQL encoded for consistency reasons.

We should be consistent with this; let's not introduce different encodings in the introspection, we already chose a way for defaultValue let us reuse that.

However, if we decide to introduce an Any scalar at some point, we could introduce a valueAsJson field to expose these things differently.

I agree that the complications of twice encoding the value are negligible since this is static data and does not need to be constantly parsed.

[michaelstaib]

That does not mean I am against Any :)

But I think we should not tie us to Any or Struct or any other proposal that is out there and by doing so blocking this feature.

[rivantsov]

metadata vs appliedDirectives

I am still strongly in favor of 'appliedDirectives':

1. HotChoc implementation added 'appliedDirectives' - because the name explains it all, no new concepts needed.
2. All new 'metadata' concepts need to explained; while after all explanations, user/reader would discover, that it is in fact 'applied directive' (based on its fields); and would be puzzled why we (WG) chose this metadata name.
3. Again, I bring strong arguments that it is NOT metadata that we have here; other platforms do not name it 'metadata' (.NET Attributes, Java Annotations).

Naming is super-important! And remember Occam's razor: "entities should not be multiplied beyond necessity"

Need to parse returned arg values from strings.

I actually do not see it as a big problem, for now at least. It depends on what format we serialize the values. GraphQL format - yes, it would be problematic. The client does not have a GraphQL parser, by default. But if we serialize as Json - no problem, the client already has Json deserializer, all responses from server are json. All it needs to do with argValue string is unescape it (like all escaped double quotes) and then use json deserializer to read it as Type that is known from directive definition.

One minor inconvenience with Json format is that in Graphiql, when you run introspection query, the arg values will show as escaped Json, which would be a bit ugly for complex input types. But I think it's just inconvenience. No impact on runtime; 'parsing twice' - well, I would expect client would run introspection queries once, not as routine, so runtime perf impact would negligible.

We can plan for the future to improve it. The best way is to introduce Any scalar (or struct), which would mean: for value of this field expect some Json subtree, as Json, not escaped string. Json value can be a simple value (123) or complex subtree for input type. The client can deserialize the subtree into an object if the type is known (like in our case with arg values).

This is for the future, for now we can use Json String. But anticipating the future we can name the field "valueJson", so that we can add "value" in the future:

type __ArgValue {
  name: String!
  valueJson: String!  # now 
  value: Any          # added in the future
}

So in the future we will have both, and I don't think it's a problem. The client might choose one or another, json tree or json string, depending on situation.

'metadata' keyword in directive declaration and isMetadata field

Whether we use AppliedDirective or Metadata as basic names, I think the 'metadata' keyword in directive declaration is confusing, better name would be 'public' or 'private', directly expressing the meaning:

directive @myCustomMetadata(myValue: String) metadata repeatable on FIELD # original

# vs  
directive @myCustomDir(myValue: String) private repeatable on FIELD # suggested 

I would suggest 'private' keyword, meaning 'do not expose'; by default all public, only a few marked as private.

But in fact, I would really argue to have NO keyword at all. Just look at the situation closely. We declare a private, non-exposed directive, return it's declaration in __Schema.directives list. We say to the client: this directive is defined by the server. But we won't show you where it's applied, it is a secret. Then - what's the point?!!! Why show the dir definition at all?

How it should work then with 'privates'? Just like Michael described with appliedDirective implementation in HotChocolate - in the class that represents the directive in code, there is an internal flag that indicates if it is public, exposed or not. It is internal, server-only thing, and the dir is not exposed at all, all done by server code. So the spec and introspection do NOT need any 'private' keyword or 'isPrivate' field in intro type.

I hope I explained it clear enough. Things private to server are not of concern of the spec! This is a clear illustration to the point I was arguing in the WG meeting, regarding GraphQL formal definition and scope. If we established that GraphQL is 'communication protocol' then it would clearly set upfront that server-only private things are OUT of spec. And we would not have to even start discussing things like 'how to indicate that it is server-side only private thing'. Please think about this in this light.

[leebyron]

I still slightly prefer metadata or something synonymous since it describes why these are being exposed (or applied) rather than just stating the fact that they are in fact applied.

When I first heard the original "applied directives" proposal I was confused by it - it wasn't clear to me why exposing applied directives was good, or what this was for. As soon as it was clarified as a mechanism for "schema metadata" it became much more clear to me. I value that clarity of purpose and hope to find some way to include it.

One way to do this might be combining my suggestion above with the original post:

directive @myCustomDir(myValue: String) metadata repeatable on FIELD

type __Field {
  metadataDirectives: [__DirectiveValue!]
}

[michaelstaib]

I would prefer GraphQL encoding as we already use that with the default values. The introspection should be consistent as a whole and not have different encodings for essentially the same thing. Also, the GraphQL encoding is better for things like enums. This still leaves open to introduce projections if that is ever needed.

Regarding the keyword. Is our intention that metadata directives represent pure metadata or is it just a switch to make them visible through introspection. I like the metadata term better than saying exposed but the term should match our intend here. repeatable for instance is very clear.

If we go the modifier route :) public might be the right keyword.

directive @myCustomDir(myValue: String) public repeatable on FIELD

[michaelstaib]

type __Directive {
  # ...
  isPublic: Boolean
}

type __Field {
  publicDirectives: [__DirectiveValue!]
}

[yaacovCR]

I still slightly prefer metadata or something synonymous since it describes why these are being exposed (or applied) rather than just stating the fact that they are in fact...

I tend to think the opposite, that because we are introducing a feature that could/will be used by users in different ways, we should use names that describe what the feature does (introspectable directives: public, exposed, etc) rather than how we expect users to use the feature (metadata). [aside: generally, if we find the resultant name unsatisfactory, perhaps that is because our implementation does not match our goal? In this case, I am fine with the name 'publicDirectives' or even 'introspectableDirectives'...]

This is especially true because I assume that even if public/exposed directives are adopted, a more robust method of extending introspection (such as proposed by @IvanGoncharov or @benjie) may eventually follow. We should be careful to avoid a potential clash in feature description.

Having said all that, I would also add that I favor 'annotation' over metadata, as this is not necessarily data about data (eg: createdAt) but rather data about types, etc, so a more generic term is appropriate.

[benjie]

If we represent metadata via a string that needs parsing (similar to defaultValue), then changes to the metadata that require new GraphQL syntax would cause existing applications to fail to parse the value entirely, causing a breaking change. This severely limits schema evolution - for example you couldn't safely add an (optional) argument to a directive that accepts a new type if that new type would introduce new syntax to the stringified form.

So long as we represent metadata in a way that does not require a parser (or only requires a parser that will never change, such as the JSON parser), extending metadata with new fields (e.g. new directive arguments) should not break existing clients.

[rivantsov]

@bbakerman

One challenge I see with that is more and more graphql servers are composed and not monoliths. Think Apollo Federated servers as the most famous example (but there are others) where there might not be code behind specific directives in a controlled sense versus what they can declare. So I think this bolsters the case for a declarer of a directive to be able to indicate whether it should be exposed.

Well, I do not agree that "exposed" or "public" flag on directive helps in this case. As far as I see it, we are talking about this setup:

(client) <-> (AFS: Apollo Federation Server) <-> (MGS: Multiple GraphQL Servers)

(based on my understanding of how federation works):
Apollo defines a few directives that MGS should use in their schemas to make Federation work. Apparently, these directives would be 'public' since they need to show up in individual schemas and introspection returned to AFS. But then, Apollo should understand that these dirs should NOT show up in the federated schema or introspection that it returns to clients; so AFS should omit them in its final federated schema, although these dirs are marked as public/exposed. So it would be custom Apollo filtering action anyway, based on a list of specific list of Apollo's 'behind the scene' directives. I do not see how the 'public' flag helps in this and similar cases.

[michaelstaib]

The argument here is more that there is really no code for the directives. Typically you can reference a GraphQL document that has these directives and then use them. So you need something in the SDL to tell the server that it is a public directive.

[rivantsov]

@leebyron @michaelstaib

Just want to remind about huge disadvantage of GraphQL encoding of values - the need for GraphQL parser on the client. That is technically not a big deal for defaultValues - most default values are primitive scalar values, and their string representations are the same for Json or GraphQL; these values can be converted simply by using conversion functions available directly in the language (js, something like convertFromString). I guess it's very rare that you have some complex input object with constant default value.

In the case here, this will happen way more often, when we have input type as input value for directive. With Json representation, it is trivial, Json deserializer is always there in the client; since any graphQL response is Json. But bringing in GraphQL parser - that might be different story, it a whole separate library, not sure it is readily available for different languages, and you need to integrate it, learn its API etc.

So I would suggest that having a light inconsistency with defaultValue is tolerable in this case, for the sake of easier, primitive handling of Json. We can look at how to 'ease' the inconsistency problem, like allow both encodings? or extra defaultValueJson, optional/nullable for now? This in fact would be a relief for clients, since again, Json is easier for them.

[michaelstaib]

most default values are primitive scalar values

The same could be said about directives. Most directives I have seen in the wild have simple scalar arguments.

But in any case, this is not a good argument for or against it since this is up to the user, and if you rely on your JSON parser in both cases, if you have an object or enum there, then you will fail.

An actual better argument for a different encoding is that the default value in most cases is not used by user components, it is more used by tooling to expose the default values.

As for exposed directives, they could gain usage in actual client applications where directives would, for instance, expose validation specifics or what have you.

Both arguments have their flaws, I think. Let's be consistent here, so there is one way to interact with such serialized values.

We could introduce for both defaultValue and value as suggested a projection that allows to access them with an Any scalar. But I would introduce a separate field for that defaultValueAsJson and valueAsJson.

Do not get me wrong. I see the issues here on the encoding; that was also my initial remark.

[bbakerman]

I am not sure if this proposal was just outlining where the "metadata" (aka applied directives) might be applied in introspection but would it be all the places you can put a directive on schema element?

type __Schema {
  # ...
  metadata: [__Metadata!] # Example of this being added to all things.
}

type __Type {
  # ...
  metadata: [__Metadata!] # Example of this being added to all things.
}

type __Field {
  # ...
  metadata: [__Metadata!] # Example of this being added to all things.
}

type __EnumValue {
  # ...
  metadata: [__Metadata!] # Example of this being added to all things.
}

type __InputValue {
  # ...
  metadata: [__Metadata!] # Example of this being added to all things.
}

[rivantsov]

yes

[michaelstaib]

This proposal will replace the appliedDirective solution you guys did with GraphQL-Java and I did with Hot Chocolate.

[IvanGoncharov]

@leebyron I'm still formulating my opinion about this proposal in general.
But I also discovered a technical problem with parsing values in GraphQL format.
Note: this is not an issue for defaultValue since, in practice, it is used just for documentation purposes.

We can't parse values in GraphQL format without access to parseLiteral of custom scalars based on existing algorithms in a spec.
Custom scalars can choose any valid GraphQL syntax to represent their value.
A theoretical example would be a scalar that uses Name node to represent its value:

scalar YesNoMaybe

directives @answer(value: YesNoMaybe!) on OBJECT_DEFINITION

type SomeType @answer(value: Maybe)

More real-life examples are custom numeric scalars implemented in any major ecosystem (JS, java, C#, etc.) some ecosystems have support for arbitrary long numbers (e.g. graphql-java has GraphQLBigInteger).

directives @number(value: BitInteger) on OBJECT_DEFINITION

type SomeType @answer(value: 111111111111111111111111111111111111111111)

Note: if the value goes through scalar's serialize function, it has been adapted to serialization protocol (e.g. long numbers converted to strings) and is handled according to a rules on serialization protocol.

So that means we can't parse the value literals using input type of directive arguments since we don't have access to parseLiter on a client.
That means we can't use any of the existing paths in Lee's diagram:
https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png
So it means that implementations need to implement their equivalent of valueFromASTUntyped that handles all such edge cases, and I think such algorithm need to be documented in the spec.

In general, I just want to emphasize that before this change, GraphQL Literal syntax was only used as input format. As for defaultValue, I never saw it being used for anything beyond showing it as a literal value in docs. Using it for exposing values of directives effectively makes it an output format that needs to be parsed/coerced without access to server-side methods of custom scalars.

[andimarek]

The link in specifiedByUrl leads to documentation page on the scalar.

To clarify that a bit: it is not just documentation, but it is a specification. And it is also suppose to be stable and fixed, allowing to be used as key to identity the implementation (and hence the parseLiteral logic).

[rivantsov]

@andimarek
I do not think this automatic integration is even possible! keep in mind that there are different clients on different platforms - js, ts, java, .NET. HotChoc has its own client (banana cake or smth), it is written in .NET. And there are server-side platforms.

The custom scalars are implemented on server, possibly on different platform; NGraphQL offers GraphQL client component written in c#. So assume Graphiql (implemented in js) connects GraphQL server implemented in .NET, with some custom scalar also implemented in .NET. Even if the server provides a link to its .NET scalar implementation, how Graphiql possibly can use it?

[andimarek]

@rivantsov I think there is a misunderstanding. A custom scalar spec (like https://www.graphql-scalars.com/date-time/) is suppose to be an implementation neutral spec. It is not bound to any specific platform or technology.

For example for the DateTime one it describes the valid literal values, but it doesn't describe the representation of the values at runtime in JS or Java or .Net. This is up to the implementation to choose.

Iit describes are the valid literal values (the input for parseLiteral if you will so). This enables me to write a JS implementation of the spec and a Java one. Now the server is implemented in Java, but the result of the introspection of the metadata/applied directives is a GraphQL literal, which is well defined in the custom Scalar spec and therefore I can use it in my JS client as input for my parseLiteral of my JS DateTime implementation.

[rivantsov]

... the result of the introspection of the metadata/applied directives is a GraphQL literal, which is well defined in the custom Scalar spec and therefore I can use it in my JS client

Ok here is a scenario

1. I am a .NET developer, building an app, and I found a cool GraphQL API CoolGraphQLService, and want to use it.
2. I want to explore the API using Graphiql. I open Graphiql and point it to CoolGraphQLService URL.
3. Graphiql crashes or shows an error. It turns out CoolGraphQLService defines and implements a couple of custom scalars. Graphiql does not know about them, and how to parse them. They have specifiedByUrl links, let's say I get this links through Graphiql.
4. I do not know js, I cannot extend Graphiql parser. How can I make it work?!
5. Should I write to Graphiql maintainers begging them implement support for these custom scalars following their 'platform-independent' descriptions? Sit and wait?
6. Other case: forget about Graphiql. Let's say I plan to use ChillieCream's client in my app. it is NOT MY Client. To work with CoolGraphQLService, should I ask ChillieCream folks to implement support for these scalars?

the point is - it is not MY CLIENT.

[rivantsov]

I'd like to mention that this challenge with custom scalars - it is also there for json encoding, although to much lower degree. The client can just use a json value (or json subtree) and treat it as a custom scalar's atomic value. No need for further custom parsing with a GraphQL parser.

[smyrick]

I really like this approach of adding the new metadata: [__Metadata!] to all the type-kinds. Right now there are two special cases that the spec has opted in to include for introspection: isDeprecated and specifiedBy.

In theory, these introspection values could be moved to the metadata approach where the spec reserves the "deprecated" and "specifiedBy" keys and would allow the spec to handle Input deprecation or @experimental and other future unknown enhancements without changing the __Type at all.

To that end, if we do implement it so that other existing introspect-able info is available, maybe the spec should add this info under the keys "graphql/deprecated" and "graphql/specifiedBy" so we can have a blanket reserved coverage of any "graphql/*" keys?

[benjie]

Sorry for the delay in getting back; I've had a busy August!

Though a straightfoward mapping of directives, I feel that this and the appliedDirectives approach (which are essentially the same, except for naming and nullability) fall short when you consider application consumption of metadata, which is one of the things that I think schema metadata could really unlock.

The way I see it, there are two main use cases for schema introspection and they're essentially governed by which of the two introspection entry-fields you use:

• __schema is used by "whole schema" introspection which is typically for tooling (GraphiQL, GraphQL Code Generator, Relay, etc); typically used at build-time where large amounts of data isn't a big deal
• __type(name: String!) is used for "per-type" introspection, which is typically in the applications themselves at run time, where over-fetching should be avoided

The __type field, I feel, is under-used because it is not particularly useful due specifically to the lack of metadata. Once we support schema metadata, its usage could explode ─ but we need to keep the requirements of the clients in mind, namely:

• we shouldn't over-fetch data (preserve client bandwidth)
• we shouldn't require additional tooling (keep bundle sizes low)
• we shouldn't break clients when we extend the metadata (don't require a parser!)

Unfortunately the appliedDirectives approach fails all three of these to varying extents.

I've prepared a few slides on some of the use cases I'm particularly excited about that granular parser-less metadata would enable; please have a quick read (it won't take long!):

https://docs.google.com/presentation/d/1e6o2kd3fVc_DQH1O8RxJo-idZM0kTOx-q322coNeIIo/present

[bbakerman]

Love the presentation approach btw

If I have it right you are proposing that the meta data be provided in JSON format always. So far the graphql spec does NOT mandate JSON as a transport format but if I have your idea right then this would mandate a JSON transport format.

There certainly is one advantage in using JSON format versus "graphql format" and that is that graphql format cannot represent all the keys that JSON can

For example imagine this JSON

"icon" : {
   "size16-16" : "https://image16.jpg",
   "size32-32" : "https://image16.jpg",
}   

This is illegal in graphql format because of the naming restrictions (a-zA-Z_0-9)

icon {
   size16-16 : "https://image16.jpg"
   size32-32 : "https://image16.jpg"
}   

[benjie]

Love the presentation approach btw

Thanks! I spent significantly more time than I should have on that 😅

If I have it right you are proposing that the meta data be provided in JSON format always.

Not exactly; I'd actually propose that we use the struct type to back the directives approach. In introspection, the struct type can be queried as if it were an object type (except the selection sets are optional - if you don't provide a selection set then it's equivalent to selecting all fields (and so on, recursively)). So struct would come out in the same kind of format as any other GraphQL field result. In SDL we could still just use directives as we do currently. (Though I'd prefer a dedicated new syntax for metadata to differentiate directive "instructions" from metadata "annotations," I fear that ship has already sailed with @deprecated, @specifiedBy, etc. effectively being annotations rather than instructions.)

[LunaticMuch]

Out of my curiosity? Is there any appetite to carry on with this? I would have a lot, and time to spare running chats or working group, but not sure whether the community wants to invest into solving for metadata within the specs or just leaving to some external approach such as plugins for apollo or similar?

[benjie]

This definitely needs solving, and comes up frequently - the challenge is deciding which trade-offs we're happy with. Once major concern I have with this particular approach is that a change in syntax introduced in a later spec version could break existing clients since their parsers might no longer be able to parse the new syntax. I'd rather avoid parser-based solutions to sidestep this problem entirely. (This is the main drawback of just adding an sdl field too. It's a nice convenience, but either it would need to accept a spec version number (or a lot of arguments to control which syntaxes it included), or we'd need to be okay with it breaking all our existing tooling when new syntax was added.)

[LunaticMuch]

Fair enough. I had the feeling that because of the challenge, we keep parking this. I am wondering how much we could break with an sdl-like implementation. Not saying none, but also, most of tools, do not really care if you inject an additional property in the introspection result right? I actually tested this today by myself with both a yoga self-built plugin and the other cited above. Both graphiql and voyager were working fine, simply not caring about it. I understand this is a limited and non-factual view of the problem. How could I help more on this?

[benjie]

do not really care if you inject an additional property in the introspection result right?

I think you're not quite following what I mean. Let's imagine that we extend type __Schema { sdl: String } and consider this schema fragment:

type Mutation {
  doTheThing(
    number: Float
  ): Boolean
}

Our tooling can query this sdl and use it for typegen or whatever.

Imagine in a schema update we introduce a new argument to our mutation, and that argument uses a type that uses a new keyword, e.g. struct:

type Mutation {
  doTheThing(
    number: Float
    struct: Struct
  ): Boolean
}

# `struct` is not a previously supported keyword, so this is
# not parseable - the entire SDL now cannot be parsed!
struct Struct {
  a: Int
  b: Int
} 

A tool that could parse the previous SDL can likely not parse the new SDL, raising a parsing error. Anything built to use this sdl: String field will break each time a new type of syntax is introduced. This very much limits its utility to top-level dev tooling that you can keep up to date and makes it much harder to use in deeper parts of the system. Imagine you had to upgrade your entire Federation architecture because one of the subschemas now uses a newer GraphQL feature... not ideal.

A tool that is built to use introspection without needing any parsing a) wouldn't request things it doesn't know about, and b) could be built to ignore things it doesn't understand (which you can't do with something that needs parsing: when would the ignore "stop" so that parsing could continue?).

This applies to the sdl: String field, but there are similar things you might consider for the applied directives approach - e.g. what if GraphQL added a binary type that uses syntax like b"QXJiaXRyYXJ5"? Anything built to parse the stringified values from the appliedDirectives approach would now fail to parse, breaking existing users.

[LunaticMuch]

I now get you 🙇🏻, thanks. I was coming from a limited view and some assumptions such as "I would not change the SDL to add the metadata" and "I would let the client to decide it wants to receive metadata information".
But ok, in both cases, they could be possible solutions to a problem, but not the only one. I am gonna read the whole struct proposal piece.