graphql/graphql-spec

This repository is the home of the GraphQL specification, the document that defines exactly how the GraphQL query language should behave. GraphQL is a query language for APIs created at Facebook that lets a client ask for the precise pieces of data it needs from a backend service, rather than receiving a fixed response. The spec itself lives in markdown files under the spec folder, and the latest published version is hosted on graphql.github.io. The README is clear about who this repository is for. The target audience is not the average developer using GraphQL in an app, but people building GraphQL implementations and tools in different languages. The spec exists so all those implementations agree on the same rules, which is what allows GraphQL to be adopted across many backend environments. Most of the README is a walkthrough that introduces the core ideas of GraphQL through an example based on the original Star Wars trilogy. It starts by defining a type system, with types like Human and Droid that have fields such as name, id, and homePlanet. It then shows how to add enums, like the three Star Wars episodes, and how to share common fields through an interface called Character. The walkthrough explains nullability, marking a field as non-null with an exclamation mark, and introduces the special Query type that acts as the entry point a client uses to start asking questions. From there it covers the query language itself, how a server validates and executes those queries, and how clients can introspect a schema to discover what is available. Previous versions of the spec are kept at permalinks tied to release tags, and the project recommends linking to a specific tagged version when referencing GraphQL in other writing. The reference JavaScript implementation, GraphQL.js, lives in a sister repository and is used throughout the example code.