# Graven

> Graven is an open specification for a zero-copy binary serialization format and its schema language (.graven), with a compiler (gravenc), lockfiles that refuse incompatible schema changes, frozen conformance vectors and a reference implementation in Rust.

Source code: https://github.com/lpj145/graven. Start with the guide for AI assistants: it has the schema syntax, the rules gravenc enforces, the commands and the Rust API in one page. Every page below is Markdown.

## Docs

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

## Optional

- [History](docs/history/index.md): how the format was designed and benchmarked (not normative).
- [Proposal 0001: imports](docs/proposals/0001-imports.md): the design of imports between schema files.
- [Complete documentation in one file](llms-full.txt)