RFC: @matches directive

[magicmark]

This RFC proposes @matches as a way for clients to express what types they support when receiving an array of unions of polymorphic types:

SDL

union Media = Book | Movie | Opera

type Query {
  getMedia(supports: [String!] @matches): [Media]
}

Query

query GetMedia {
  # @matches ensures that these values are valid, and that the resolver always returns compatible types.
  getMedia(supports: ["Book", "Movie"]) {
    ... on Book { title author }
    ... on Movie { title director }
  }
}

See the full RFC here: https://github.com/magicmark/graphql-wg/blob/patch-18/rfcs/MatchesDirective.md

(This came out of a GraphQLConf unconf discussion topic - thanks to @captbaritone @rbalicki2 @benjie! :)

[rbalicki2]

FYI the link to the RFC doesn't work. Edit: now it does! :)

[magicmark]

@rbalicki2 fixed

[rbalicki2]

Overall, love it!! Haven't read it entirely fully, but a few nits for clarity:

• it might be worth clarifying that the supported argument applies to the inner type, i.e. in my3DField(supported: [String!]! @matches): [[MyUnion!]!] supported must be typenames for MyUnion and to clarify that this proposal works for MyUnion, and [MyUnion!]!, etc.
• it might be worth adding getMedia(supports: ["Book"]) { __typename } # error: ... on Book not found
• I think that it's probably worth considering treating the server validation piece and the operation-validation piece as independent, at least in terms of inclusion in the spec. I of course like both!
• Response validation: Is the effect of throwing an error that the nearest nullable parent field becomes null? I think there're at least two other possible server responses: fail the request (i.e. data: null, errors: nonEmpty) and find some parent field that is a union and return the error variant. I don't know if that's worth explicitly calling out; that might be already understood by server engineers.

[magicmark]

thanks @rbalicki2! thanks for the feedback, will incorporate this.

I think that it's probably worth considering treating the server validation piece and the operation-validation piece as independent, at least in terms of inclusion in the spec. I of course like both!

Happy to do this in whichever way makes the most sense to most people, but my thinking was this makes the most sense as a combined proposal rather than splitting them into independent proposals that might land at different times. I'd be slightly nervous about folks using the new directive without validation rules, since it seems too easy to construct an invalid query by passing in garbage array arguments (with relay this is impossible)