English for Cap'n Proto Serialization

Cap’n Proto is frequently introduced by comparison to Protocol Buffers, and getting that comparison right in words matters — “it’s like protobuf but faster” undersells the actual architectural difference. This guide covers the vocabulary for discussing it precisely.

Key Vocabulary

Zero-copy deserialization — Cap’n Proto’s defining property: the wire format is identical to the in-memory representation, so reading a message requires no parsing or copying step, only pointer arithmetic. “The latency win isn’t from a faster parser — there is no parser. Zero-copy deserialization means the bytes on the wire are already the object in memory.”

Schema (.capnp file) — the interface definition language file describing message structure, compiled to generate typed accessors in a target language, conceptually similar to a .proto file but with a different evolution model. “Update the .capnp schema first, regenerate the bindings, then update the code that constructs the message — the order matters because the generated types are strict.”

Field ordinal (not field number reuse) — the numeric position assigned to each field in a Cap’n Proto schema, which, unlike protobuf, cannot be freely reordered without breaking wire compatibility since layout is positional. “Don’t reorder fields in the schema even though it looks harmless — Cap’n Proto’s field ordinals are tied to memory layout, not just an ID, so reordering breaks compatibility differently than in protobuf.”

Message builder / reader — the two distinct API surfaces Cap’n Proto generates: a builder for constructing a message in memory, and a reader for accessing an existing message’s fields without mutation. “You’re using a reader API but trying to set a field — that won’t compile. You need a builder if you’re constructing rather than just inspecting a message.”

RPC (Cap’n Proto RPC) — the built-in remote procedure call layer that supports promise pipelining, allowing a client to chain calls on a not-yet-resolved result without waiting for a round trip. “With promise pipelining, we can call a method on the result of another call before that first call even returns — the RPC layer batches it into a single round trip.”

Arena / segment — the underlying memory region Cap’n Proto allocates messages into, which can span multiple segments for large messages, relevant when debugging serialization size or allocation behavior. “The message spilled into a second segment because it exceeded the default arena size — that’s not a bug, but it’s worth knowing when reasoning about allocation counts.”

Common Phrases

• “Is this actually a zero-copy read, or are we still doing a full parse somewhere in this path?”
• “Did we update the .capnp schema, or is this generated code out of sync with the current definition?”
• “Are we reordering fields here — that’s not safe the way it might be in protobuf.”
• “Do we need a builder for this, or is a reader sufficient since we’re only inspecting the message?”
• “Is this RPC call using promise pipelining, or is it doing a full round trip per call?”

Example Sentences

Explaining the performance benefit in a design doc: “We’re proposing Cap’n Proto specifically for the hot path where message size is large and read frequency is high — zero-copy deserialization avoids the parse cost entirely, which is the dominant cost with protobuf at this scale.”

Reporting a schema evolution bug: “A client on the old schema started reading garbage after we changed field order — we should have added new fields at the end instead of reordering, since Cap’n Proto ties field position to memory layout.”

Discussing RPC design: “Using promise pipelining here lets us chain the lookup and the subsequent call into effectively one round trip, which matters a lot given the network latency between these two services.”

Professional Tips

• Lead with zero-copy deserialization when explaining performance to someone comparing against protobuf — it’s the actual mechanism, not just “it’s optimized.”
• Warn explicitly about field ordinal stability in schema reviews — this is the single most common way teams break wire compatibility coming from a protobuf mental model.
• Distinguish builder and reader APIs by name in code review, since using the wrong one produces confusing compile errors that are easy to misdiagnose as something else.
• Mention promise pipelining specifically when discussing RPC latency — it’s a distinguishing feature worth naming rather than folding into a vague “it’s more efficient” claim.

Practice Exercise

1. Explain zero-copy deserialization to someone familiar with protobuf, in two sentences.
2. Write a schema review comment warning about reordering fields.
3. Describe, in your own words, what promise pipelining accomplishes.