Crate codas

Expand description

Markdown-defined data that serialize to and from bytes on any platform—from web apps to robots!

§What’s a Coda?

Codas document the structure of related types of data, each containing one or more fields. Codas’ data can encode to and decode from raw binary data streams, which makes them extra-helpful for building distributed or embedded apps that speak different languages or rely on low-level networking.

Note: For those familiar with other data interchange formats, codas are similar to Protocol Buffers and Cap’n Proto.

Each data type in a coda can have the following kinds of fields:

Unsigned integers from 8 to 64 bits (u8, u16, u32, and u64).
Signed integers from 8 to 64 bits (i8, i16, i32, and i64).
Signed floating-point integers from 32 to 64 bits (f32 and f64).
Booleans (bool).
UTF-8 encoded text (text).
Other user-defined data types (“nested” data)
Lists of any of the things listed above.

For information on how codas’ data is coded to and from binary data, refer to the codec docs.

§How do I make a Coda?

Codas are made with Markdown:

# `Greeter` Coda
An example coda.

## `Request` Data
Data type in this coda named `Request`.

+ `message` text

## `Response` Data
Another data type in this coda named `Response`.

+ `message` text

+ `friends` list of text

   This field of a `Response` is a list
   of text, instead of a single `text`.

+ `request` Request

   This field of a `Response` is a copy of the
   `Request` that the response is for, showing
   how we can nest data types within each other.

This example describes a Greeter coda with two kinds of data: Request and Response. Both of these data contain a message text, while the Response data contains a list of text called friends and a copy of the original Request:

Every coda begins with a header (#) containing the name of the coda (Greeter, in this example) followed by the word Coda.
Every data description begins with a header (##) containing the name of the data type (Request or Response, in this example) followed by the word Data.
Each field inside of a data description is a list item, starting with a + and followed by the name and then the type of the field.
Any text directly below a coda header, data header, or field item will be parsed as Markdown documentation for that item.

The order of Data and their fields (+) matters: If data or fields are re-arranged, the binary encoding of that data may also change.

§How do I use a Coda?

The easiest way to get started with Codas is with Rust via the codas-macros crate.

§From Other Languages

Try out the live code generator on codas.dev!

§Can I evolve or extend my Codas?

Yes! Codas are designed to evolve as a system’s needs change:

New data types can be added to the end of a coda.
New fields can be added to the end of a data type.
Existing fields and data types can be renamed.

If a system receives data of a new type it doesn’t support, or containing new fields it doesn’t support, the new information will be gracefully ignored.

Conversely, if a system receives data that’s missing newly-added fields, the missing fields will be gracefully populated with default values.

§Relative Performance (“Benchmarks”)

Operation	`codas`	`prost (proto3)`
Encode	`49ns (20M/s)`	`51ns (19.6M/s)`
Decode	`110ns (9M/s)`	`118ns (8.5M/s)`

Comparative performance of different scenarios we’ve written benchmarks for. Exact numbers will vary between platforms.

codas-macros: Macros for generating Rust data structures for any Coda.
codas-flow: Low-latency, high-throughput Bounded queues ("data flows") for (a)synchronous and event-driven systems.

§License

Licensed under the MIT license. Refer to the license file for more info.

Note: Codas and their related Rust Crates were originally maintained by Alicorn Systems on GitLab. On May 12th, 2025, Alicorn Systems transferred Codas and their related Rust Crates to With Caer, and relicensed them under the MIT license. Note: This documentation is auto-generated from the project’s README.md file.

Modules§

codec: Binary data encoder and decoder (“codec”).
langs: Coda code generators.
parse: Coda Markdown parser.
stream: Utilities for reading and writing streams of binary data, with optional support for std::io::Read and std::io::Write on platforms supporting them.
types: Built-in data types and their in-memory representations.

Macros§

sized_byte_array: Macro which generates a new type a struct wrapping a fixed-size [u8] array, enabling sype-safe sharing.

Crate codasCopy item path