# graphql-spec: the Working Draft behind every GraphQL implementation

> The graphql/graphql-spec repository holds the editable Working Draft of the GraphQL specification, not a library you install into an app. It is for people writing servers, clients, validators and codegen tools, and its build pipeline is a spec-md render plus a spelling and Prettier gate.

**graphql/graphql-spec** — GraphQL is a query language and execution engine tied to any backend service.

- Repository: https://github.com/graphql/graphql-spec
- Website: https://spec.graphql.org
- Stars: 14,596 · Forks: 1,155
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/graphql-graphql-spec

## What graphql-spec actually is, and who it is written for

The README is blunt about its audience: the target reader is not the client developer but people building GraphQL implementations and tools. That single sentence separates this repository from every GraphQL tutorial you have read. The specification lives in markdown files under /spec, and the published output is a rendered document, not a package you import. The README also frames the project as a coordination point, arguing that broad adoption across backend environments, frameworks and languages requires a collaborative effort across projects and organizations. The draft carries the subtitle of a Working Draft created by Facebook, and the latest release listed in the repository is September2025, with the two before it dated October2021 and June2018. That release cadence is the honest signal about what working here looks like. If you need a stable citation, the README recommends linking to a tagged permalink for the particular referenced version rather than the moving draft. If you are writing an execution engine, a static validator, or a schema introspection tool, this is the document that defines whether your behaviour is correct. If you are building a product on top of an existing GraphQL library, you are not the audience.

## The mechanism: markdown in /spec, rendered by spec-md

There is no runtime here. The data flow is markdown to HTML. The specification text sits in /spec, the build script is build.sh, and the test target for the build is a spec-md invocation against a metadata file:

```bash
spec-md --metadata spec/metadata.json spec/GraphQL.md > /dev/null
```

That command is what npm run test:build runs, according to package.json. The metadata file supplies document information to spec-md, and spec/GraphQL.md is the entry document that pulls in the rest. A watch script exists for local editing: nodemon is configured with the extensions json and md and execs npm run build on change, which tells you the authoring loop is edit markdown, wait for a rebuild, refresh the browser. Two auxiliary scripts hang off the same pipeline. One updates "Appendix D -- Specified Definitions" by running a Node script and then formatting that file with Prettier. The other, .github/algorithm-format-check.mjs, checks the formatting of algorithms in the spec. The prose itself is written in a shorthand type notation, and the README walks through a Star Wars example to introduce the type system, the query language, execution semantics, static validation and type introspection. The type system example starts from a single type and grows it:

```graphql
type Human {
  name: String
}
```

From there the README adds an id and homePlanet, defines an Episode enum, introduces Droid, extracts a Character interface that both types implement, and finally marks id as non-null with an exclamation mark. That progression is the document's own teaching order, and it is worth following before you touch the normative text.

## Building the spec locally and reading a real section

The repository is private in the npm sense: package.json sets "private": true, so there is nothing to publish and nothing to install globally. You clone it and build it. The dev dependencies are cspell, nodemon, prettier, spec-md, and graphql at ^17.0.0-alpha.9, which is worth noticing: the reference implementation is a development dependency of the specification repository, not the other way around. After cloning, install dependencies and run the build:

```bash
npm install
npm run build
```

The build script is ./build.sh. If you want the live rebuild loop while editing markdown, the watch script wraps nodemon over the same build. The full test target chains three checks:

```bash
npm test
```

According to package.json, that expands to test:spelling, test:format and test:build. Spelling runs cspell over spec/**/*.md plus README.md and LICENSE.md. Format runs prettier --check over markdown, yml, yaml and json, and on failure prints a suggestion to run npm run format. Build runs the spec-md command shown above. A first real use, then, is not calling an API. It is opening a section of the spec, changing a sentence, running npm test, and watching Prettier or cspell reject you before the renderer ever gets a chance. The Prettier configuration in package.json sets proseWrap to always and trailingComma to none, which is why prose diffs in this repository reflow whole paragraphs rather than single lines.

## Where the contribution model will frustrate you

The repository carries a CONTRIBUTING.md, a STYLE_GUIDE.md, a cspell.yml and a signed-agreements directory. Those last two are the practical constraint. Spelling is enforced as a test, so a new term in a normative paragraph fails CI until it is added to the cspell configuration, and the format check means an unformatted markdown table blocks the build. A signed-agreements directory in the repository root is the other gate: contribution is not a pull request away for everyone, and the process around it is a governance question rather than a technical one. The README does not document a rollback path for a merged specification change, and there is no versioning scheme described beyond release tags. That matters more than it sounds. Implementers ship against a version of the spec, and if a clarification lands on main between releases, the draft and the released text can disagree. The README addresses this directly by telling you to link to a tagged permalink, which is an admission that the draft is not a citation target. The three most recent releases are dated 2025-09-04, 2021-10-27 and 2018-06-11. A gap of roughly four years between the 2021 and 2025 releases is not a sign of neglect, but it should recalibrate how you plan around specification changes if your roadmap assumes annual revisions.

## graphql-spec versus GraphQL.js: different jobs, different failure modes

The natural comparison is GraphQL.js, the reference implementation the README points to for a more full-featured view of the type system. The difference in approach is categorical. GraphQL.js is executable JavaScript: you define a schema, run queries, and get results, and its starWarsSchema.ts and starWarsData.ts files back the Star Wars example in the README with real objects. graphql-spec is prose that those behaviours are checked against. If you want to know what a field resolver should do, you read the spec. If you want to do it, you install the implementation. The README itself makes the distinction when it notes that the shorthand notation is convenient for describing the shape of a type system while the JavaScript implementation is more full-featured and allows types and fields to be documented. That is why graphql is listed as a devDependency here at an alpha version: the spec repository tracks the implementation loosely, and the implementation is not what ships from this repository. Choosing between them is not a trade-off, it is a question of whether you are writing behaviour or defining it.

## Licence and the cost of staying current

package.json declares the license as OWFa-1.0, the Open Web Foundation Agreement, while the repository metadata reports NOASSERTION and the root contains a LICENSE.md. Those two signals do not match, and anyone reusing specification text in their own documentation should read LICENSE.md and the signed-agreements directory before assuming a permissive grant. This is not legal advice; it is a note that the machine-readable and human-readable licence signals disagree here, which is unusual enough to check. The upgrade cost is low in the mechanical sense and high in the interpretive sense. There is no dependency to bump. The work is re-reading normative text after a release and checking your implementation against it, and the release history shows that work arrives in bursts rather than on a schedule. The build toolchain is pinned to specific versions, including prettier 2.8.2 and spec-md 3.1.0, so a fresh clone should reproduce the published output without version drift.

## Conclusion

Adopt graphql-spec as a reference if you are writing a GraphQL server, client, validator or code generator, and pin your links to a release permalink such as the October2021 tag rather than the draft URL. Do not clone it expecting a runtime: package.json is private, the only dependencies are cspell, nodemon, prettier, spec-md and graphql, and nothing here executes a query. If you only consume GraphQL through an existing library, read the published spec page instead and skip the repository. Before quoting any rule, open the tagged permalink for the version you target and run npm run test:build locally to confirm the draft you read is the draft that renders.

## FAQ

### Is GraphQL still relevant in 2026?

The repository's most recent release is September2025, and the README describes GraphQL as a query language for APIs created by Facebook with a specification maintained as a point of coordination across projects and organizations. The last push to the main branch was on 2026-09-17.

### What does GraphQL stand for?

The repository does not expand the name as an acronym. The README describes it only as a query language for APIs, and the specification covers a type system, query language and execution semantics, static validation, and type introspection.

### Is GraphQL just JSON?

The specification repository is markdown prose rendered by spec-md, so it is not JSON at all. The query language and the type system are defined in the text under /spec, and the README's examples are written in GraphQL type shorthand rather than JSON.

## Sources

- [graphql/graphql-spec on GitHub](https://github.com/graphql/graphql-spec)
- [Issues](https://github.com/graphql/graphql-spec/issues)
- [Project website](https://spec.graphql.org)
- [README](https://github.com/graphql/graphql-spec/blob/main/README.md)
- [Releases](https://github.com/graphql/graphql-spec/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/graphql-graphql-spec