Vexil

Exact binary protocols, defined as types.

Vexil is a schema language and toolchain for compact, deterministic binary protocols. A schema defines both the data model and its representation on the wire: u4 is four bits, @varint selects unsigned LEB128, and fields are packed LSB-first without platform-dependent padding.

Generate Rust, TypeScript, Go, or Python codecs from the same contract. Every generated target carries the schema's canonical BLAKE3 hash, while vexilc compat makes compatible and breaking schema changes explicit.

Vexil is pre-1.0. Start with the support matrix and current limitations, especially for new cross-language deployments.

See the contract

namespace sensor.packet

enum SensorKind : u8 {
    Temperature @0
    Humidity    @1
    Pressure    @2
}

message SensorReading {
    channel  @0 : u4
    kind     @1 : SensorKind
    value    @2 : u16
    sequence @3 : u32 @varint
    delta_ts @4 : i32 @zigzag
}

That schema fixes details which are often left to handwritten codecs:

• channel occupies exactly four bits;
• kind uses its declared ordinal;
• sequence uses unsigned LEB128;
• delta_ts uses ZigZag followed by LEB128;
• the canonical schema hash is independent of comments and formatting.

The wire is deliberately not self-describing. Both peers compile the schema they intend to use and can compare its hash before exchanging application data.

Start in five minutes

Install the compiler:

cargo install vexilc

Or build this checkout with Rust 1.94 or later:

cargo build --release --bin vexilc

Check a schema and generate a Rust codec:

vexilc check telemetry.vexil
vexilc codegen telemetry.vexil --target rust --output telemetry.rs

For a runnable first project:

cargo run --manifest-path examples/quickstart/Cargo.toml

The quickstart guide explains the schema, generated source, exact bytes, and round trip.

Current main includes editor diagnostics for unsaved single-file documents, but this work is newer than the published vexilc 0.6.0 CLI. To try it, build vexilc from source and configure the editor's language-client command as vexilc lsp. This first LSP surface reports compiler errors and warnings; it does not yet load projects or provide completion, navigation, hover, formatting, or a bundled editor extension. See the LSP reference for the exact capability boundary.

Why Vexil

Wire choices are reviewable

Bit widths, field ordinals, integer encodings, collection bounds, and evolution annotations live in the schema instead of being scattered across encoders.

Output is deterministic

Canonical map and set ordering, defined scalar encodings, and padding rules make the same value produce the same bytes for a given schema.

Drift is visible

Generated schema hashes identify the exact contract. vexilc compat classifies schema changes and reports the required SemVer level before a protocol ships.

Choose a generated target

Target	Runtime	Current evidence
Rust	vexil-runtime	Broad compile, golden, Clippy, and byte-vector coverage
TypeScript	@vexil-lang/runtime	Native build/tests and broad byte-vector coverage
Go	packages/runtime-go	Native execution over a representative shared wire matrix
Python	vexil-runtime	Static and native execution over a representative shared wire matrix

“Representative” is intentional. Go and Python do not yet have the same breadth of generated-code evidence as Rust and TypeScript. Verify the schemas and target combinations used by your application.

Read Generating Code for target-specific commands and Compatibility and Limitations for the adoption boundary.

Follow the examples

1. Quickstart — check, generate, encode, and decode one schema.
2. Project evolution — imports and compatible versus breaking changes.
3. Cross-language interop — one fixture encoded by four generated targets.
4. Live telemetry — stateful delta frames from Rust to a browser.

Run the complete checked path with:

python scripts/examples.py check all

Documentation

• Documentation book
• Language specification
• Binary wire-format specification
• CLI reference
• Support matrix
• FAQ
• Changelog

The specifications are normative. Guides and examples explain the contract but do not replace it.

Contributing

Bug reports, focused documentation corrections, corpus cases, and code changes are welcome. Read CONTRIBUTING.md before opening a pull request. Language or wire changes follow the lightweight RFC process in GOVERNANCE.md.

License

Licensed under either MIT or Apache-2.0, at your option.