Encode one value two ways in two applications
This example serializes one nested archive of messages twice, under two applications that disagree
about how bytes and dates should look. It is an example from cgp-serde, which
rebuilds Serde's Serialize and Deserialize traits as components of
Context-Generic Programming (CGP). The data types name no encoding, and the two
applications differ in three wiring lines, which is the whole difference between the two JSON
documents they produce.
New to CGP?
basic introduces the wiring table this page builds on. For CGP itself, the Hello
World tutorial shows contexts and wiring with a smaller program, and
Coherence explains why plain Rust allows only one encoding per type,
which is what two applications here get around. This page can be read without them.
The problem
The task is to serialize the same data, an archive of messages with byte fields and dates, for two applications that disagree about how it should look: one wants bytes as hex and dates as RFC 3339 strings, the other bytes as base64 and dates as Unix timestamps. Both applications use the same Rust types, and the choice has to apply at every level of nesting.
Without CGP
With Serde, a type has one Serialize impl in the whole program. Vec<u8> and DateTime<Utc>
already have theirs, in serde and in chrono, and Rust's orphan rule stops an application from
writing another. So the encoding is chosen per field, with #[serde(with = …)] attributes or
wrapper types, and each struct definition carries one set of choices. Two applications that want
different choices need two sets of structs, or code that converts the shared structs into
application-specific copies before serializing. This page keeps one set of structs and gives each
application its own choices.
Run it
From the root of the cgp-serde repository, run the example:
cargo run -p cgp-serde-examples --example messages
It serializes the same archive twice and prints each document, shown below.
cargo test -p cgp-serde-examples --example messages checks both against this exact JSON. From
the first application, AppA, bytes are hex and dates are RFC 3339 strings:
{
"decryption_key": "746f702d736563726574",
"messages_by_topics": [
{
"encrypted_topic": "416c6c2061626f757420434750",
"messages": [
{
"message_id": 1,
"author_id": 2,
"date": "2025-11-03T14:15:00+00:00",
"encrypted_data": "48656c6c6f2066726f6d20527573744c616221"
},
{
"message_id": 4,
"author_id": 8,
"date": "2025-12-19T23:45:00+00:00",
"encrypted_data": "4f6e65207965617220616e6e697665727361727921"
}
]
}
]
}
From the second, AppB, bytes are base64 and dates are Unix timestamps:
{
"decryption_key": "dG9wLXNlY3JldA==",
"messages_by_topics": [
{
"encrypted_topic": "QWxsIGFib3V0IENHUA==",
"messages": [
{
"message_id": 1,
"author_id": 2,
"date": 1762179300,
"encrypted_data": "SGVsbG8gZnJvbSBSdXN0TGFiIQ=="
},
{
"message_id": 4,
"author_id": 8,
"date": 1766187900,
"encrypted_data": "T25lIHllYXIgYW5uaXZlcnNhcnkh"
}
]
}
]
}
The data names no encoding
The archive is three nested structs, from
messages.rs:
#[derive(CgpData)]
pub struct EncryptedMessage {
pub message_id: u64,
pub author_id: u64,
pub date: DateTime<Utc>,
pub encrypted_data: Vec<u8>,
}
#[derive(CgpData)]
pub struct MessagesByTopic {
pub encrypted_topic: Vec<u8>,
pub messages: Vec<EncryptedMessage>,
}
#[derive(CgpData)]
pub struct MessagesArchive {
pub decryption_key: Vec<u8>,
pub messages_by_topics: Vec<MessagesByTopic>,
}
Byte fields appear at every level, and dates in the innermost struct. Nothing in the structs says
how either is written. CgpData only exposes the fields
to generic code, and Vec<u8> and DateTime<Utc> belong to other crates, so in Serde their
encoding would be whatever their existing Serialize impls chose.
Each application is a context with its own table
AppA is a type that stands for the first application, which is where its choices live. It has no
fields, and its wiring table names a provider for each type the archive contains:
pub struct AppA;
delegate_components! {
AppA {
open {ValueSerializerComponent};
@ValueSerializerComponent.<'a, T> &'a T:
SerializeDeref,
@ValueSerializerComponent.[
u64,
String,
]:
UseSerde,
@ValueSerializerComponent.Vec<u8>:
SerializeHex,
@ValueSerializerComponent.DateTime<Utc>:
SerializeRfc3339Date,
@ValueSerializerComponent.[
Vec<EncryptedMessage>,
Vec<MessagesByTopic>,
]:
SerializeIterator,
@ValueSerializerComponent.[
MessagesArchive,
MessagesByTopic,
EncryptedMessage,
]:
SerializeRecordFields,
}
}
The open statement lets the table choose by the type being serialized, and each @ entry makes
one choice, as in basic. A bracketed list gives several types the same provider.
AppB is a second context with the same table, except for three entries:
@ValueSerializerComponent.[
i64,
u64,
String,
]:
UseSerde,
@ValueSerializerComponent.Vec<u8>:
SerializeBase64,
@ValueSerializerComponent.DateTime<Utc>:
SerializeTimestamp,
SerializeHex and
SerializeBase64 are two providers for the same type,
Vec<u8>, and so are SerializeRfc3339Date
and SerializeTimestamp for DateTime<Utc>. As
Serde impls they would conflict, since a type can have only one. As entries in two contexts' tables
they do not, because each choice holds only within the context that makes it.
Coherence explains why that is allowed.
A choice reaches every level of nesting
Neither table says anything about where a Vec<u8> appears, and yet every byte field in the
archive, at all three levels, follows its context's choice. That is because no provider encodes the
values inside the one it is given.
SerializeRecordFields walks a struct and asks
the context to serialize each field, and
SerializeIterator walks a collection and asks the
context to serialize each item. Each of those requests goes back through the same table, so the
context's choice for a type applies wherever the type turns up. Re-entrant
providers explains the mechanism.
Entries the traversal needs
Because every nested value goes back through the table, the table needs an entry for every type the traversal reaches, not only for the fields in the data. Four entries exist for that reason:
- Each vector of structs gets
SerializeIterator. AVec<EncryptedMessage>is a value the traversal reaches, so it needs an entry of its own besides the one forEncryptedMessage. - The generic reference entry,
<'a, T> &'a T, sends every reference toSerializeDeref, which serializes the value behind it. Walking a borrowedVec<EncryptedMessage>yields&EncryptedMessage, and this one entry covers every such reference. Stringis wired, although no field is aString, because the hex, base64, and RFC 3339 providers each produce a string and ask the context to serialize it.i64is wired inAppB, although no field is ani64, becauseSerializeTimestampturns the date into ani64and asks the context to serialize that.
The last point is the easiest to miss, and the change at the end of this page shows what happens without it.
Serializing through an ordinary Serde API
Each context's wiring is asserted by a
check_components! table listing the seven types it
serializes. Then the example hands each context and the archive to serde_json, through a helper
that accepts any context able to serialize the archive:
fn to_pretty_json<Context>(context: &Context, archive: &MessagesArchive) -> String
where
Context: CanSerializeValue<MessagesArchive>,
{
serde_json::to_string_pretty(&SerializeWithContext::new(context, archive)).unwrap()
}
SerializeWithContext pairs a context with a value
and implements Serde's own Serialize trait, so any Serde format accepts it unchanged. Any error is
serde_json's own, which is why neither context wires an error type.
Try a change
Remove i64 from AppB's UseSerde entry, leaving [u64, String], and run
cargo cgp check. The check on AppB fails, and the tool names the
missing entry as the root cause:
error[E0277]: [CGP-E001] missing wiring for `@ValueSerializerComponent.i64` on `AppB`
= note: root cause: [CGP-E113] missing wiring for `@ValueSerializerComponent.i64` on `AppB`
Every checked type that contains a date fails, and all for one reason. Below the root cause, the
tool prints the chain that leads to it: from MessagesArchive through SerializeRecordFields, the
vectors, the references, and EncryptedMessage, down to SerializeTimestamp, which asks AppB for
an i64 it has no entry for. The fix is to put i64 back. cargo cgp check leads with the root
cause for the classes it recognizes, and the tool does not yet reshape every class.
The pattern
This example shows two applications choosing different implementations for the same types, without a conflict. Each application is a context, the serialized value is a parameter of the component, and a context's table decides the provider for each value type, including types from other crates. Because every provider hands nested values back to the context, one entry decides a type's encoding everywhere in the value. The idea is CGP's local answer to Rust's coherence rule, explained in Coherence, and Modularity hierarchy places it among the alternatives.
The cost is the table each application writes. AppA and AppB share all but three entries and
still list every one, and both carry entries, such as the reference entry and AppB's i64, that
serve the traversal rather than the data. The shared entries can move into a namespace the two
contexts join, as the last step of wiring a
context shows, but
the traversal's entries are still there to write. A program that needs one encoding per type gets it
from Serde's derive with none of this.
Where to go next
- Architecture: the design this example rests on, one idea per page.
- Wiring a context: how to find every type a traversal reaches, and how to check the table.
- Coherence: the Rust rule that gives a type one impl, and how CGP restores choice one context at a time.
- Announcing cgp-serde: the post that announced the library, which presents this two-application demo. Its code predates the current design.
- How to stop fighting with coherence (RustLab 2025): the talk that used this demo live, with a transcript.
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.