cddl-zig compiles a CDDL schema into Zig 0.16 types and CBOR codecs. Generated
code uses native Zig structs, optionals, slices, scalar types, and tagged unions;
it validates the schema on both decode and encode. The companion cddl_runtime
module implements strict RFC 8949 decoding and core deterministic encoding.
The project has no package dependencies.
- Zig 0.16.0
For a user-local release build:
git clone https://github.com/Mewski/cddl-zig.git
cd cddl-zig
zig build -Doptimize=ReleaseSafe --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
cddl-zig versionzig build installs into zig-out by default. --prefix "$HOME/.local" uses
Zig's standard installation-prefix mechanism and places the executable in
$HOME/.local/bin; add that directory to the shell profile for persistent use.
For checkout-local development instead:
zig build
./zig-out/bin/cddl-zig versionzig fetch manages source dependencies; it does not install command-line tools.
Given packet.cddl in an application's root:
packet = {
id: uint,
? label: tstr,
data: [* int],
}
Generate the Zig module:
mkdir -p src
cddl-zig check packet.cddl
cddl-zig generate -o src/packet.zig packet.cddlAdd the cddl package to the application's package manifest:
zig fetch --save git+https://github.com/Mewski/cddl-zig.gitzig fetch --save writes the dependency URL and content hash to
build.zig.zon. Commit that manifest so the fetched package contents remain
reproducible.
Generated source imports the runtime as cddl_runtime. Inside
build(b: *std.Build), using the application's existing target, optimize,
and exe, add:
const cddl = b.dependency("cddl", .{
.target = target,
.optimize = optimize,
});
const packet = b.addModule("packet", .{
.root_source_file = b.path("src/packet.zig"),
.target = target,
.optimize = optimize,
.imports = &.{
.{ .name = "cddl_runtime", .module = cddl.module("cddl_runtime") },
},
});
exe.root_module.addImport("packet", packet);The dependency also exports cddl for programs that invoke the compiler API
directly:
exe.root_module.addImport("cddl", cddl.module("cddl"));Creating a named module does not automatically expose it to an executable;
addImport supplies the corresponding @import dependency edge.
The schema above exports Packet and PacketCodec. This complete Zig 0.16
example encodes and decodes one value:
const std = @import("std");
const generated = @import("packet");
pub fn main(init: std.process.Init) !void {
const allocator = init.gpa;
const values = [_]i65{ 1, -2 };
const packet: generated.Packet = .{
.id = 7,
.label = "ready",
.data = .{ .field_0 = &values },
};
const bytes = try generated.PacketCodec.encode(allocator, packet);
defer allocator.free(bytes);
var decoded = try generated.PacketCodec.decode(allocator, bytes, .{});
defer decoded.deinit();
std.debug.assert(decoded.value.id == packet.id);
}decode returns an arena-owning Decoded. Its .value and all nested slices
remain valid until Decoded.deinit. encode returns allocator-owned bytes.
validate checks a native value without producing CBOR.
cddl-zig check [options] <file>
cddl-zig generate [options] <file>
cddl-zig runtime -o <directory> [--check]
cddl-zig explain <CODE>
cddl-zig help [<command>]
cddl-zig version
Run cddl-zig help <command> for the complete option set.
checkruns parsing, semantic analysis, codec planning, and source generation, but writes no generated source.generatewrites to stdout by default.-o <path>atomically replaces a file only when its bytes differ.--check -o <path>writes nothing and exits 3 when the file is missing or stale.runtimewrites every source file required bycddl_runtimeinto a directory. Its--checkmode detects missing or changed runtime files, ignores unrelated files, writes nothing, and exits 3 when the runtime is stale.explainprints the stable explanation for anEdddddiagnostic code.helpprints general or command-specific usage;versionprints the package version.
Schema commands accept exactly one file or - for stdin. Generated modules
export every non-generic type rule. The root—the first rule by default, or the
rule named by --root <rule>—must be a non-generic type rule; choosing a root
validates that requirement but does not filter the generated exports.
Diagnostics support bounded retention, byte-accurate locations, and explicit
color control. --diagnostics json writes one JSON document to stderr for schema
and I/O outcomes. Argument-parsing errors remain plain text; later usage errors,
including an output path that resolves to the input, use the JSON document.
Exit codes are 0 for success, 1 for schema diagnostics, 2 for usage or an unknown
diagnostic code, 3 for stale --check output, 4 for I/O or input-limit failures,
5 for out of memory, and 70 for an internal error. cddl-zig help is the
authoritative command summary.
| CDDL | Generated Zig |
|---|---|
uint |
u64 |
int |
i65 |
| float types | f64 |
tstr, bstr |
[]const u8 |
| fixed array or map group | struct |
? entry |
optional field |
| repeated array entry | slice field |
| heterogeneous choice | union(enum) |
prelude scalar choice (int, float, bool) |
native scalar |
| tag | struct containing number and content |
Public rule names use PascalCase. Field names use snake_case. Collisions are
resolved deterministically. Generated modules check cddl_runtime.abi_version
at compile time.
See docs/mapping.md for ownership and mapping details.
The frontend parses and normalizes the RFC 8610 core language using the RFC 9682 grammar and the RFC 8610 Appendix D prelude. The generated-code support boundary is narrower and explicit below. The runtime follows RFC 8949; its high-level value encoder emits core deterministic CBOR.
Generation deliberately rejects constructs for which this backend does not yet
have an exact native mapping. Current hard errors include recursive type graphs,
group alternatives, repeated group splices, dynamic or repeated map keys,
.regexp, .cborseq, and non-RFC-8610 control vocabularies. No unsupported
construct is widened to any or silently ignored.
The exact accepted and rejected sets are documented in docs/standards.md.
cddl_runtime can also be used independently. Its public API includes:
Encoder,Decoder,Value, andValue.EntryencodeValueAlloc,decodeValue, andvalidateDecodeOptionswith optional deterministic-input checking- finite depth, item, string, cumulative-allocation, and work limits
- RFC 8949 map-key equivalence and duplicate-key rejection
The decoder accepts valid non-preferred CBOR by default. Set
require_deterministic to reject non-preferred arguments, float widths, and map
ordering. Generated codec encode, encodeValueAlloc, and Encoder.writeValue
emit core deterministic CBOR. MapBuilder orders encoded keys and rejects
equivalent keys, but callers must supply deterministic key and value encodings.
Lower-level Encoder methods such as writeEncoded, writeFloat32, and
writeFloat64 deliberately preserve caller-supplied bytes or widths;
writeMapHeader requires keys to follow in deterministic order.
zig build fmt-check
zig build test
zig buildArchitecture and invariants are in docs/architecture.md.
The Unlicense. This software is dedicated to the public domain.