Documentation
The specification is the normative text; everything else explains how to use it and how the reference implementation is built and tested.
- Getting started
- Install gravenc, create a schema and lockfile, and wire up code generation (including Rust build.rs).
- Coming from JSON
- Translate JSON data into a Graven schema, convert existing files, and choose how to store arrays.
- Good practice
- Advice for designing schemas, storing collections and reading untrusted data, with the reason behind each tip.
- Specification
- The normative wire format: layout, presence, verification, envelope, compatibility, conformance.
- Binary layout
- Every kind of value on the wire, byte by byte, with real messages encoded by the reference implementation.
- Schema language
- The .graven language, evolution rules, the compiler workflow and the generated API.
- Validation
- Built-in rules (range, len, finite, known), custom checks, evolution and generated validation API.
- Tools
- gravenc: check, update, diff, inspect, JSON conversion and log scanning; editor support.
- Conformance vectors
- The 42 frozen vectors and how to test an implementation against them.
- Benchmarks
- The reference implementation against FlatBuffers and Cap'n Proto: size, allocations and time on one machine.
- Testing
- How the reference implementation is tested: suite, fuzzing and Miri.
- The future
- Where Graven can be applied, what already works for each area, and what is still to be built.
- For AI assistants
- A compact guide for language models, plus llms.txt and llms-full.txt for tools that load documentation.
- History
- How we got here: the designs, plans and benchmarks that led to the format, in order (not normative).
- Changelog
- Release history.