JSON Schema and GraphQL

[dEv Jones]

Does anyone have thoughts or experience on how JSON Schema might be used in tandem with GraphQL (http://graphql.org/)?  In a nutshell, GraphQL allows developers to ask an API for *exactly* the fields and relations they want using a JSON-like syntax (thank Facebook, the author of HTML-like JSX and other tastes-like-chicken inventions for this).  GraphQL is probably most useful for publicly consumed APIs where requests are so diversified that offering "canned" response formats might be too restrictive. The potential is there to reduce bandwidth usage because users can ask for exactly which fields they need.  There's also the potential to eliminate an SDK because GraphQL might be an acceptable protocol for accessing data without the need for an intermediary layer.

However, there are a couple weird things about GraphQL.  One is that a GraphQL API does away with the REST notion of "resources" -- instead, GraphQL APIs usually offer just a single endpoint where you post your GraphQL queries.  The second strange thing is that the GraphQL API "documentation" seems to rely on code introspection -- literally it sniffs your code and offers up some information to the client about which objects and fields are available.  It reminds me a bit of "automagically" generating API documentation by scanning for JavaDoc notation in your code.

Is there any room for JSON Spec in a GraphQL API?  Its data schema is sorta immovable lest the automagic spell be broken, so one would have to tread carefully to convert that schema into a JSON Schema document, but one might go as far as to argue that a JSON Schema document would be unnecessary given the GraphQL conventions.  

Thoughts?