cgp-serde
cgp-serde rebuilds Serde's Serialize and Deserialize traits as components
of Context-Generic Programming (CGP), a language extension for Rust with pluggable trait
implementations at compile-time. With Serde, a type has one encoding for the whole program, chosen
by whoever owns the type. With cgp-serde, the encoding of each type is chosen by the application
instead, so two applications can write the same value differently, and neither needs to own the type
or wrap it.
cgp-serde is a proof of concept. It replaces Serde's per-type implementations and keeps everything
else: Serde's data model, its formats such as serde_json, and any Serialize impl a type already
has. Its generic providers cover structs with named fields, enums whose variants each hold one
value, and the standard collections, and scalars and every other type are encoded through their
own Serde impls. These pages show
what the design makes possible and where it stops.
One value, two encodings
The library's own demonstration encodes one nested archive of messages under two applications,
AppA and AppB. The data types derive nothing from Serde. Each application is a context, a
type that stands for that application and holds its choices, and its wiring table names an
implementation, or provider, for each type it encodes. The two tables are the same except for
three lines. AppA has these:
@ValueSerializerComponent.[u64, String]: UseSerde,
@ValueSerializerComponent.Vec<u8>: SerializeHex,
@ValueSerializerComponent.DateTime<Utc>: SerializeRfc3339Date,
and AppB has these:
@ValueSerializerComponent.[i64, u64, String]: UseSerde,
@ValueSerializerComponent.Vec<u8>: SerializeBase64,
@ValueSerializerComponent.DateTime<Utc>: SerializeTimestamp,
Serialized through serde_json, the first message of the archive comes out like this from AppA:
{
"message_id": 1,
"author_id": 2,
"date": "2025-11-03T14:15:00+00:00",
"encrypted_data": "48656c6c6f2066726f6d20527573744c616221"
}
and like this from AppB:
{
"message_id": 1,
"author_id": 2,
"date": 1762179300,
"encrypted_data": "SGVsbG8gZnJvbSBSdXN0TGFiIQ=="
}
Bytes are hex in one and base64 in the other, and dates are RFC 3339 strings in one and Unix
timestamps in the other, at every level of nesting. In Serde, Vec<u8> and DateTime<Utc> each
have one Serialize impl in the whole program, and a struct's derive fixes how its fields are
written, so producing both documents from the same structs needs a second set of wrapper types. Here
each choice is one wiring line in the application that makes it. The
messages example walks through the whole program.
What the design shows
cgp-serde exists to show what CGP's per-context wiring does to a trait every Rust developer knows, and it shows three things.
The application chooses the encoding. The serialized value becomes a parameter of the component, and the context becomes the type that implements it, so each application makes its own choice for each value type, including types it does not own. The component design page explains the move, and Coherence explains why it lets choices overlap without conflicting.
A data type needs no serialization derive. A struct that derives CGP's general-purpose
CgpData is serialized by generic providers that read
its fields, so a crate can define serializable types without depending on serde at all. See
derive-free records.
A deserializer can draw on its context. Every provider receives the context, so a deserializer can take a service from it while it works, such as an arena to allocate borrowed values into. Serde's traits have no place to pass one. See context services.
A user who only wires a context meets little of CGP beyond one wiring table. Writing a provider is where CGP's traits become the subject, and that is where the learning cost falls.
Status and costs
cgp-serde is a demonstration of the design, and these are the costs a reader evaluating it should know first:
- It is a proof of concept. The library is lightly tested and not meant for production use. The limitations page describes the limits of its design.
- A context names every type it encodes. The wiring table has an entry for each type a value
contains, including in-between types such as a
Vecof structs, so it is longer than the data definitions it serves. A type with no entry is a compile error, not a runtime surprise. - Mistakes produce long compile errors. A missing entry deep inside a nested type fails to
compile, and the compiler's raw message lists every step it took to find it. Checking the context
with
check_components!and reading the error withcargo cgp checknames the missing entry:cargo cgp checkleads with the root cause for the classes it recognizes, and the tool does not yet reshape every class. The debugging guide shows the common mistakes. - Its output suits self-describing formats. JSON and RON work with it as they are. Length-prefixed binary formats, such as postcard, do not accept the maps and sequences its generic providers write. See using a format.
- It builds on stable Rust. The repository pins its toolchain, and nothing needs nightly.
The examples
The examples are the repository's runnable programs, walked through as short tutorials in the order they teach:
basic— one struct written to JSON and read back, with its bytes as hex and its errors in the context's error type.messages— one nested archive encoded two ways by two contexts that differ in three wiring lines.events— an enum of chat events, each holding a struct, written and read back by two applications with different encodings.
Two more examples deserialize borrowed values into an arena that the context supplies. Their pages are still being written, and context services explains the design they show.
The rest of the section
The architecture pages explain the design one idea at a time. The guides cover wiring a context, writing a provider, using a format, and debugging the wiring. The reference has a page for each provider. The comparison with Serde sets out what cgp-serde keeps, adds, and lacks, and when plain Serde is the better choice, and the limitations page describes where the design stops.
Running it
Clone the repository and run an example from its root
with cargo run -p cgp-serde-examples --example <name>. The repository's toolchain file selects the
Rust version, and no example needs a network or any program outside the build.
To use cgp-serde from your own crate, add its crates from crates.io beside cgp: cgp-serde for
the components and core providers, then cgp-serde-extra, cgp-serde-json, cgp-serde-alloc, or
cgp-serde-typed-arena for the providers your wiring names, and a Serde format such as
serde_json to write the output:
[dependencies]
cgp = "0.8.0"
cgp-serde = "0.3.0"
cgp-serde-extra = "0.3.0"
serde_json = "1"
Where to go next
basic: the first example, and the one to read first.- Modularity hierarchy: where cgp-serde's shape sits among the ways CGP lets code choose an implementation.
- Hello World: a first CGP program, for a reader new to CGP.
- Announcing cgp-serde: the post that announced the library, with its motivation. Its code predates the current design.
- cgp-serde's release notes: what each official release changed, and the steps to upgrade from the one before.
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.