Generate Zig from FlatBuffers schemas. Serialize native values. Borrow views from existing bytes.
Quick start · Copyable examples · Runtime API · Compiler API · WebAssembly compiler · More examples
The build generates a rocket module from rocket.fbs.
Inside a function with std imported, an allocator, and the generated Rocket type:
const rocket: Rocket = .{
.id = 7,
.fuel = 80,
.pilot = "Ziguana",
.payload = &.{ 1, 2, 3 },
};
const result = try rocket.serialize(allocator, .{});
defer result.deinit(allocator);
try Rocket.verify(result.bytes, .{});
const view = try Rocket.read(result.bytes);
try std.testing.expectEqual(@as(u32, 7), view.id);
try std.testing.expectEqual(@as(f32, 80), view.fuel);
try std.testing.expectEqualStrings("Ziguana", view.pilot.?);Or for comptime buffer
const rocket: Rocket = .{
.id = 7,
.fuel = 80,
.pilot = "Ziguana",
.payload = &.{ 1, 2, 3 },
};
const capacity = comptime flatzz.storage.capacityFor(Rocket.Schema, rocket, .{});
var storage: [capacity]u8 align(flatzz.storage_alignment) = undefined;
const bytes = try rocket.serialize(&storage, .{});
try Rocket.verify(bytes, .{});
const before = try Rocket.read(bytes);
try std.testing.expect(try Rocket.update(bytes, .fuel, 79));
try std.testing.expect(try Rocket.update(bytes, .pilot, "Pilot01"));
try Rocket.verify(bytes, .{});
const after = try Rocket.read(bytes);
try std.testing.expectEqual(@as(f32, 80), before.fuel);
try std.testing.expectEqual(@as(f32, 79), after.fuel);
try std.testing.expectEqualStrings("Pilot01", after.pilot.?);
try std.testing.expectEqualStrings("Pilot01", before.pilot.?);
try std.testing.expectError(error.LengthMismatch, Rocket.update(bytes, .pilot, "short"));
try std.testing.expectEqualStrings("Pilot01", (try Rocket.read(bytes)).pilot.?);Copy complete test · Complete runner · Runnable source and tests
result owns the allocation. Release it once with the same allocator and keep
it alive while using borrowed views. view.fuel is the decoded scalar 80;
view.pilot borrows the string "Ziguana" from result.bytes.
The same serialize(target, options) operation accepts an allocator or an aligned
mutable buffer. Its argument type determines whether the result owns an allocation
or borrows supplied storage; the values and storage remain runtime inputs.
Copy code · Runnable source and tests
rocket.serialize(&storage, .{}) writes into an aligned caller-owned buffer
without heap allocation. The returned bytes borrow part of that storage;
reusing it invalidates the frame and its views. Serialization writes data into
the frame. The illustration is conceptual, not an exact byte layout.
Copy schema and full generated source · Schema · Runnable source
Generation happens on the host at build time. The application imports the generated module and the Flatzz runtime. The illustration omits field metadata; the copyable example includes the complete generated output.
| Operation | Purpose |
|---|---|
verify |
Traverse known schema fields and validate their reachable wire data |
read |
Decode scalars and borrow strings and structured views |
update |
Replace a present scalar, string, struct, or vector without growing the frame |
borrowMutable |
Borrow a structured field; inline structs retain mutable access |
Copy read/edit test · Mutable nested struct example · More examples · Browse online examples
update returns false when a field is absent. Strings and vectors must keep
their lengths; replacing tables or whole unions requires rebuilding. Read scalars
again after an edit. Borrowed strings still refer to the same bytes, so edits can
also be visible through earlier views.
For mapped input, the application supplies the byte slice and manages the mapping and buffer lifetime. Use explicit Builder handles when child tables must be shared; see the Builder example.
Build commands and compatibility
Run from this directory. Zig fetches the pinned Zast package when schema tools
or the Wasm compiler are enabled. Runtime, parsing, reflection, and BFBS APIs
can be checked without Zast. The default check and test steps include README
example generation through the schema tools.
| Command | Action |
|---|---|
zig build |
Install the compiler, both examples, and generated Reading |
zig build compiler |
Build and install only zig-out/bin/flatzz |
zig build wasm |
Install the reusable freestanding Wasm compiler |
zig build run-readme |
Generate Rocket; allocate, serialize, receive, read, and edit |
zig build run-mission |
Generate Mission from two FBS files; serialize with comptime-sized storage and read it |
zig build run-monster |
Generate Monster; serialize with comptime-sized storage and read its fields and union |
zig build run |
Generate Reading; serialize with buffers sized at comptime |
zig build run-builder |
Run construction, mutation, and unions with Builder |
zig build check |
Compile examples, tests, and contracts |
zig build test |
Test native runtime, FBS parsing, generated Zig, and contracts |
zig build fmt |
Check Zig formatting |
zig build docs |
Generate runtime/compiler API references into zig-out/docs |
zig build examples |
Compile the native Zig examples and their tests |
zig build check test -Dschema-tools=false |
Check and test runtime/compiler APIs without Zast |
zig build generate-reading |
Regenerate tests/fixtures/reading/reading.zig |
zig build update-zast |
Update the Zast commit and package hash from GitHub main |
zig build --help |
List targets and options |
The generated example executable is zig-out/bin/flatzz-example.
All example commands and independent example builds: example/README.md.
The sibling flatzz-site project prepares the website, API theme, and example catalogue.
The WebAssembly compiler provides FBS to Zig/schema JSON/BFBS and
BFBS to Zig/schema JSON. Other projects can request the flatzz-compiler-wasm
artifact with .@"wasm-compiler" = true; no site-specific compiler setup is needed.
Implementation layout and ownership
The public entry points are runtime.zig (flatzz) and
compiler.zig (flatzz_compiler). Applications can use the
runtime, FBS parser, reflection model, and BFBS codec without Zast. Zig source
generation uses a separate Zast-based backend; generated modules import only flatzz.
| Responsibility | Implementation |
|---|---|
| Descriptors, schema composition, and public adapters | schema.zig |
| Native graph preflight and packing | native_graph.zig |
| Checked local buffer access, ranges, and scalar reads/writes | buffer_access.zig |
| Result types and field reads from checked tables | field_access.zig |
| Storage bounds, native sizing, and owned serialized buffers | storage.zig |
| Buffer construction and table state | Builder.zig, table_builder.zig |
| Known-schema wire traversal and resource limits | Verifier.zig |
| Public FBS API, diagnostics, and options | parser.zig |
| Compiler and parser tests | test_compiler.zig, test_parser.zig |
| Sources, symbols, semantic resolution, defaults, and layout | Compilation.zig |
| Source cursor and declaration grammar | Parser.zig |
| Shared unresolved declarations and spelling helpers | model.zig |
| Reflection records and primitive facts | reflection.zig |
| Portable schema JSON writing | json.zig |
| Public BFBS API, encoding, decoding, and shared record layout | bfbs.zig, Encoder.zig, Decoder.zig, record_layout.zig |
| Source generation lifetime, lowering, and scratch expression construction | codegen.zig, Generator.zig, Syntax.zig |
| Freestanding compiler ABI and virtual source map | compiler.zig, Sources.zig |
Licensed under the European Union Public Licence v1.2.
