Dagr

Dagr ("Data Graph") is a binary serialization format for data graphs — object graphs with cycles and shared nodes — and a set of code generators that emit a complete, self-contained implementation of your schema for Swift, Rust, TypeScript, Go, Mojo, Odin and Python.

You describe a graph once, in a small Python DSL:

from dagr.dsl import DataGraph, Node, Enum, t, required
from dagr.config import Library, Swift, Rust

address_book = DataGraph("AddressBook", root_type=t.ref("Book"), node_types=[
    Node("Book", fields=["people" >> t.ref("Person").array]),
    Node("Person", fields=[
        "name"    >> t.utf8 >> required,
        "age"     >> t.u8,
        "friends" >> t.ref("Person").array,      # cycles and shared nodes are fine
        "status"  >> t.ref("Status"),
    ]),
    Enum("Status", ["single", "married", "widowed"]),
])

library = Library("AddressBook", schemas=[address_book], targets=[
    Swift(out="gen/swift", features=["lazy", "path_query", "explain"]),
    Rust(out="gen/rust", features=["lazy", "path_query"]),
], wire_format_version=1)

dagr build then generates, per language, an arena-backed typed API (no reference cycles to leak, value-type handles), byte-exact serialization and restore, and optionally zero-allocation lazy accessors, path queries that read one field straight out of a buffer, and an explain tool that annotates every byte. The generated code has no runtime dependency — the runtime is emitted alongside it.

Why Dagr

• Graphs, not trees. Cycles, back-references and shared nodes serialize naturally; the arena model is what makes that safe in every target language.
• One schema, seven languages, identical bytes. Swift, Rust, TypeScript, Go, Mojo, Odin and Python read and write the same buffers; a cross-language test corpus of ~1000 fixture permutations gates every change byte-for-byte.
• Four node layouts to choose from. Regular (vtable, evolvable), packed (compact), frozen (fixed-offset, O(1) reads) and frozen+packed — per node type, per schema (spec/16-choosing-a-node-layout.md).
• More than graphs. DataSink is an append-only record stream with the same type system (logs, event streams, attestable audit trails); SharedBuffer is a fixed-layout overlay for IPC, GPU and no-allocation embedded use, with seqlock, ring and double-buffer strategies.
• Tooling around the format. Schema import from .proto, FlatBuffers, JSON Schema and ASN.1; generation receipts and compatibility checks (dagr check); a browser schema editor (dagr ui); self-contained HTML explorers for any buffer; git diff and three-way merge drivers; an ImHex pattern exporter; a fuzzer; Arrow producers.

Install

The tool is pure Python 3.9+ with no dependencies.

pip install dagr-cli            # or: uv tool install dagr-cli;  from a checkout: pip install -e .
dagr init --name my_schema      # scaffolds schema.py + pyproject.toml
dagr build                      # generates every target in Library.targets, writes dagr.lock.json
dagr check                      # diffs the schema against the committed receipt

Compiling and running the generated code needs the respective toolchain (Swift 6.2, Rust 1.85+, Node 20+, Go 1.22+, Mojo 1.0 via pixi, Odin). Generating never does.

Targets

Documentation

• spec/ — the numbered wire-format specification and design plans; start with spec/README.md, then spec/01-motivation-for-arenas.md.
• docs/technical-feature-overview.md — every feature with an engineering assessment.
• examples/ — worked examples: an attested audit log, JWT-shaped tokens, a structured log sink, a package registry, stress graphs, a Swift↔Rust FFI demo.
• CONTRIBUTING.md — repository layout, toolchains, and the generate → test loop.

Repository layout

dagr/        the Python package: DSL, config, CLI, code generators, importers, runtime, web UI
spec/        numbered specification documents
targets/     per-language runtimes, example packages and generated test crates
tests/       test generators, runners, unit tests, fixture schemas and (generated) fixture corpora
examples/    worked examples built with `dagr build`
benchmarks/  micro-benchmarks
site/        showcase site and spec-document generators
docs/        prose documentation, blog posts, images

Generated code is not committed. After cloning, run ./regen_all.sh once to emit every generated source, fixture and test suite (see CONTRIBUTING.md).

Status

Dagr is used in production-style projects by its author and is versioned by CalVer (2026.9.0); the wire format is versioned separately per schema (wire_format_version) and checked by dagr check. Swift and Rust are the most complete targets; see CHANGELOG.md for what changed and spec/30-deferred-codegen-gaps.md for known gaps per target.

License

Apache License 2.0 — see LICENSE.