What if we treat GraphQL Queries as the API definition? - WunderGraph
CEO & Co-Founder at WunderGraph
May 20, 2021·min read
Last updated on July 19, 2026
Archive Notice
This article is archived and no longer maintained. It describes an earlier version of WunderGraph's approach to persisted operations and generated JSON Schema, which is no longer part of the current product. The examples and setup steps may not work as described. For current documentation and guidance, see WunderGraph Documentation
State of GraphQL Federation 2026
How are teams governing schema changes, handling production traffic, and measuring Federation success? Share your experience and get early access to the full report. For every valid survey completed, we'll donate $30 to UNICEF.
TL;DR
An application built on GraphQL actually has two schemas: the explicit one you get from introspection, and an implicit one you can derive from all the operations the application actually uses. If you persist those operations, each query becomes a REST-ish endpoint, and both the input variables and the response can be described as JSON Schema. WunderGraph generates that JSON Schema automatically from the queries you write, which gives you input validation, a typesafe client in any language, and even generated forms with libraries like react-jsonschema-form.
JSON Schema
In WunderGraph, we generate a JSON Schema automatically from the Queries you write. This way, you could easily modify the resulting schema to add rules like defining a minimum.
Summary
I hope you're able to take some inspiration on what's possible when we treat GraphQL Queries as the API definition. I don't think this will replace the way we currently use GraphQL APIs though. For public APIs like e.g. GitHub or Shopify it doesn't even make sense. However, as most of us use GraphQL as a private API, this pattern can help us to build better apps faster and make them more secure.
Frequently Asked Questions (FAQ)
What are the two schemas of a GraphQL application?
One is the explicit schema returned by an introspection query, listing the available queries, mutations, and subscriptions. The second is implicit, derived from all the GraphQL operations used in an application, describing their possible inputs and outputs.
How does JSON Schema fit in?
When operations are persisted, both the input variables and the response can be represented as JSON, and JSON Schema is used to define that structure, which allows validation, rules such as requiring a positive integer, and integration with existing tooling.
How does turning queries into endpoints affect the client?
The JSON Schemas for all operations can be fed into code generators to produce a fully typesafe client in any language, and because the type definitions are transpiled away before runtime, the WunderGraph client is just 2kb of JavaScript.
How does the @fromClaim directive work?
It annotates variables like email and name so the operation requires the user to be authenticated, returning a 401 if they aren't, and injects the values from the user's claims into those variables before the resolvers are called.
Does this pattern replace normal GraphQL usage?
No. It won't replace the current way GraphQL APIs are used and doesn't make sense for public APIs like GitHub or Shopify, but since most people use GraphQL as a private API, the pattern can help build better and more secure apps.