apollo-rs parses and analyzes GraphQL without panicking on bad syntax

Three crates with one job: the GraphQL language itself

apollo-rs is a workspace of Rust crates for the low-level workings of GraphQL, and the README is emphatic about scope. Nothing in these libraries is specific to Apollo, and they can be used by any project that needs standards-compliant GraphQL tooling written in Rust. The reference to the GraphQL specification is the October 2021 edition.

The three crates divide the work cleanly. apollo-compiler is a library to manipulate, semantically analyze, and validate GraphQL schema definition and query language. apollo-parser is a library to parse the GraphQL, and the README notes it is used by apollo-compiler, so the parser sits underneath the compiler rather than beside it. apollo-smith is a test case generator that deterministically produces arbitrary GraphQL documents.

That last crate deserves more attention than it usually gets. A deterministic generator is useful precisely because it is reproducible: the same seed and the same input produce the same document, which is what makes fuzzing and regression testing of a parser meaningful. The repository carries a fuzz directory and a graphql.ungram grammar file at the top level, which are consistent with that testing direction.

The layering also tells you where to start. If you only need to turn text into a syntax tree, apollo-parser is the dependency. If you need schema semantics and validation, that is apollo-compiler. If you need to generate documents to test something else, that is apollo-smith.

The parser gathers context instead of returning on the first error

The third design principle in the README is the one with the most engineering consequence. The tools are written to produce detailed diagnostics, and specifically the parser does not panic and does not return early when it hits a lexical or syntactic error. Instead it gathers as much context and information as possible and returns errors alongside the output that is valid.

That is a deliberate departure from the usual parser contract, where a parse either succeeds or fails. A caller that expects a document or an error has to be ready to handle both at once, and the shape of the returned value carries the partial tree alongside the error list. The README notes the second benefit almost in passing, since the extra context also makes the project easier to debug for its own maintainers.

For an editor or an IDE plugin, this is the difference between showing one red squiggle and showing the whole set of problems in a file. For a CI pipeline validating a schema, it means one run reports every invalid field rather than the first one, which saves a round of fixing and re-running.

The cost is that the API is not the same as a parser that returns Option or Result with a single error. Callers that want only the first failure have to decide which error to keep, and code that assumed parse failure meant no output at all has to be revisited.

A Cargo workspace with examples and a fuzz target in the tree

The repository is a Cargo workspace, and its Cargo.toml shows the members explicitly. The core is xtask/, three crates under crates/ for apollo-parser, apollo-compiler and apollo-smith, plus fuzz and an example under examples/. The workspace uses resolver = "2", so all members share one lockfile and one set of dependency versions.

The top-level entries describe the shape of the work. ARCHITECTURE.md sits next to CONTRIBUTING.md, which suggests the internals are documented for contributors rather than only for users. The fuzz directory is a workspace member in its own right, meaning the fuzzing targets are built as part of the same dependency graph rather than as a separate side project. graphql.ungram at the root is a grammar description file, the kind used to describe the language surface for fuzzing generators.

The examples directory contains validation-wasm-demo, which suggests a browser-targeted build of the validation path. The README does not describe that demo in detail, so treat it as a pointer to a working example rather than as a documented feature.

Practical reading order: the crate README for the crate you intend to use, then ARCHITECTURE.md if you need to know how the parser and compiler relate, then the crate READMEs for usage examples, which is what the README of the workspace directs you to.

There is no install recipe in the README, only crate names

The workspace README does not contain a dependency snippet, a cargo add line or a feature flag table. It names the crates and links to their directories under crates/, and it asks you to check the respective READMEs for usage examples. In other words, the workspace README is a map, and the detail lives one level down in apollo-compiler, apollo-parser and apollo-smith.

What can be stated from the workspace itself is the shape of the package set:

[workspace]
resolver = "2"

The workspace members listed in Cargo.toml are xtask/, crates/apollo-parser, crates/apollo-compiler, crates/apollo-smith, fuzz and examples/validation-wasm-demo. The examples directory also holds the validation demo, and there is a .cargo directory at the top level, which usually indicates repository-wide Cargo configuration.

So the honest guidance for a first use is to add the crate you need to your own Cargo.toml and follow that crate's README. The README points at an issue tracker for problems, with the note that apollo-rs is a living project that keeps evolving and is being used in production, and it encourages opening an issue if you run into trouble. There is no stability promise in the workspace README itself; the design principles speak of stability and reliability and of spec-compliant, idempotent APIs intended for enterprise-grade codebases, but that is a stated intention rather than a compatibility guarantee.

Rust version support and per-crate release cycles are the practical caveats

On toolchain support the README is brief and honest: apollo-rs is tested on the latest stable version of Rust, and older versions may or may not be compatible. If your organization pins Rust versions through a toolchain file or a distribution package, you are testing an unsupported combination by definition, and the README gives you no list of known-good versions to check against.

The release list shows three crates released independently rather than one workspace-wide version. apollo-parser published 0.8.7 on 2026-10-20, apollo-compiler published 1.33.0 on 2026-09-03, and apollo-smith published 0.17.0-beta.1 on 2026-08-28. Two consequences follow. First, the crates are not in lockstep, so pinning apollo-compiler does not pin the parser it depends on unless you pin that too. Second, one of the three is still carrying a beta tag, which for a generator used in test pipelines is usually acceptable but is worth naming in your own risk assessment.

The version numbers also hint at maturity differences. A parser at 0.8.7 and a compiler at 1.33.0 are on different stability tracks, and the README's own status section describes the project as evolving and in production use.

On licensing, the workspace is offered under a choice: the Apache License, Version 2.0 or the MIT license, at your option. Both license files are present in the repository root. That dual licensing means you can meet an organisation's Apache requirement or MIT requirement without asking the upstream project to change terms.

What building your own GraphQL parsing would cost you

The alternative to apollo-rs is the one most teams try first: write a GraphQL parser in their own language, or in Rust, as part of their application. It is a bad trade for schema and query validation, and the reason is visible in the design principles. The parser does not panic and does not return early, it accumulates context, and it aims to be spec-compliant and idempotent, which means running it over the same input twice gives the same result. Those are not features you get for free from a hand-written recursive descent implementation in an afternoon.

The realistic reason to write your own is that you need exactly one narrow behaviour and want no dependencies. If you only need to pull a single field out of a query string in a service that already receives parsed documents from a GraphQL server, apollo-rs is heavier than the job. If you are building a GraphQL-aware linter, a schema diff tool, a query planner or a code generator, then the parsing and validation layer is the actual product, and the diagnostics-first design of apollo-parser becomes the reason to use it.

The middle ground is also worth naming. You can depend on apollo-parser alone and skip apollo-compiler if your needs stop at syntax, which keeps the dependency surface smaller while still getting the error-collecting behaviour. The workspace structure supports that choice because the crates are published separately.

Editorial conclusion

apollo-rs fits teams that need to parse, validate or generate GraphQL documents inside Rust code and that want diagnostics with source context instead of a panic, and and pinning the latest stable Rust is effectively required, since the README lists no known-good older toolchains. Before adopting it, read the README of the individual crate you need, since the three crates have separate release cycles, and check whether the apollo-smith beta tag in the release list matters to your use case. Note that the README says nothing about a dedicated 1.0 milestone, so plan for the crate APIs to keep moving.

Frequently asked questions

Official sources

1. apollographql/apollo-rs on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases