pact 0.3.0

Compact and streamable data format that works anywhere--from web apps to robots.
Documentation

Compact and streamable data format that works anywhere--from web apps to robots.

What's a Pact?

Pacts describe the structure of related types of data, each containing one or more fields. Pact data can encode to and decode from raw binary data streams, which means pacts are extra-helpful for making distributed or embedded apps that speak different languages or rely on low-level networking.

Note: For those familiar with other data interchange formats, pacts have a lot in common with things like the proto schemas used by gRPC and the capnp schemas used by Cap'n Proto.

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

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

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

How do I make a Pact?

Pacts are made with Markdown:

# `MyGreeter` Pact
An example pact.

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

+ `message` text

## `Response` Data
Another data type in this pact 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 MyGreeter pact 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 pact begins with a header (#) containing the name of the pact (MyGreeter, in this example) followed by the word Pact.

  • 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 pact 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. In general, don't reorder things, and only add new data and fields to the end of existing data and fields.

The easiest way to get started with Markdown pacts in your own projects is via the pact-derive crate.

Can I change or "evolve" a Pact?

Yes! Pact data is designed to evolve as a system's needs change:

  • New data types can be added to any pact.
  • New fields can be added to any 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.

License

Copyright 2024 Alicorn Systems, Inc.

Licensed under the GNU Affero General Public License version 3, as published by the Free Software Foundation. Refer to the license file for more information.

If you have any questions, please reach out to [hello@alicorn.systems].