# SBE Schema Evolution: sinceVersion & actingBlockLength

> Implement zero-downtime binary protocol upgrades in FIX SBE using messageHeader actingVersion, actingBlockLength, and XML sinceVersion extension blocks.

Canonical: https://terminalledgerdesk.com/reports/sbe-schema-evolution-sinceversion-actingversion-wire-compatibility
Last updated: 2026-11-14T20:05:31.892Z

**Publication:** Terminal Ledger Desk
**Category:** Fix Protocol Sbe Ouch Session Latency
**Published:** 2026-11-14T11:15:25.915Z
**Author:** Marcus Thorne, CQF (Certificate in Quantitative Finance (CQF), Low-Latency FIX & Matching Engine Architect)
**Reviewer:** Not recorded

## Answer-first summary

FIX Simple Binary Encoding (SBE) achieves zero-downtime forward and backward wire compatibility by transmitting actingBlockLength and version in every 8-byte message header.

## Key takeaways

- Never advance SBE message cursors using compile-time sizeof(Struct); always jump by wire Header.actingBlockLength and GroupHeader.blockLength.
- Appending new fields with sinceVersion="N" at the tail of root or repeating-group blocks preserves 100% wire compatibility with un-recompiled older clients.
- When a newer v9 binary replays historical v7/v8 PCAPs, generated SBE accessors compare actingVersion < 9 and safely return the schema null sentinel.
- SBE delivers full forward/backward compatibility for just ~15 ns over unsafe C struct casts—beating Protocol Buffers by 6.1x on p99 latency.

## Related financial entities

- **CME Aurora Financial Data Center Standard** (CME-AURORA) — product: Dedicated CME Group hosting facility in Aurora, Illinois, housing the Globex matching engine and offering direct low-latency colocation to clearing members.
- **Financial Information eXchange (FIX) Protocol** (FIX-4.4) — product: Electronic communications protocol initiated in 1992 for international real-time exchange of securities transaction and market data information.
- **Financial Information eXchange (FIX) Protocol Standard** (FIX-STANDARD) — product: Universal electronic messaging standard that facilitates real-time communication of securities transactions and market data across global financial institutions.

## Analysis

Hardcoding raw C `reinterpret_cast<const NewOrderAck*>(buf)` pointers against binary exchange packets works right up until an exchange appends an 8-byte regulatory timestamp to the root block during a quarterly release—instantly shifting every trailing repeating group by 8 bytes and corrupting production parsers! FIX Simple Binary Encoding (`SBE`) solves binary schema evolution cleanly without version-negotiation handshakes by embedding two dynamic framing integers—`blockLength` (`actingBlockLength`) and `version` (`actingVersion`)—inside every 8-byte wire header.

## Three-Rule Invariant of Non-Breaking SBE XML Schema Extensions

Under the [FIX SBE standard](/engines/fix-protocol-messaging-standard) used by CME Globex (`iLink 3` and `MDP 3.0`), Eurex, and institutional internal buses, a schema publisher can increment `version` (e.g., `v8 -> v9`) without forcing clients to recompile on Day 1 provided three strict XML layout laws hold:

1. **Immutable Existing Offsets**: Existing fields in the root block or inside a repeating group NEVER change byte offset, width, or primitive type.
2. **Tail-Only Extension (`sinceVersion`)**: New fields are appended strictly at the **end** of the root fixed block (or at the end of a repeating group block) tagged with `sinceVersion="9"`, increasing the schema `blockLength` from e.g. `88` to `96` bytes.
3. **Stable Ordering of Groups & VarData**: Repeating groups and variable-length strings follow the root block in unchanged declaration order.

![SBE 8-byte messageHeader showing actingBlockLength and actingVersion enabling v8 decoder to skip v9 extension fields](/api/figure?type=flow&title=SBE%20Wire%20Header%20%26%20Forward-Compatible%20Offset%20Jumping&subtitle=How%20v8%20compiled%20decoders%20safely%20traverse%20v9%20extended%20root%20and%20group%20blocks&steps=1.%208B%20SBE%20Header%3A%3AblockLen%3D96%20%20%20tmplId%20%20%20schemaId%20%20%20ver%3D9%7C2.%20Read%20v8%20Fields%3A%3ADirect%20MOV%20at%20fixed%20offsets%200..87%7C3.%20Skip%20Extension%3A%3AJump%20base%20%2B%20actingBlockLength%20%2896%29%7C4.%20Group%20Stride%3A%3AStep%20ptr%20%2B%3D%20group.blockLength%20%2828B%29&metrics=HEADER%20SIZE%3A%3A8%20Bytes%3A%3A4%20x%20uint16%20little-endian%7CVERSION%20CHECK%3A%3A1%20Cycle%3A%3APredicted%20branch%20on%20v9%20field%7CDOWNTIME%20REQ%3A%3A0%20Seconds%3A%3ARolling%20minor-version%20deploy%7CREPLAY%20SPAN%3A%3AMulti-Year%3A%3Av9%20binary%20reads%20v5%E2%80%93v8%20PCAPs)

## How `actingBlockLength` Enables Both Forward and Backward Compatibility

Generated C++ / Rust SBE flyweight decoders (`Real Logic sbe-tool`) never advance past the root block using their *compile-time* `SCHEMA_BLOCK_LENGTH`! Instead, they read the *wire packet* header `actingBlockLength` (`uint16_t` at byte `0`) and `actingVersion` (`uint16_t` at byte `6`):

- **Forward Compatibility (v8 Client Receiving Newer v9 Exchange Packet)**: The wire header reports `actingBlockLength = 96`, `actingVersion = 9`. The v8 client reads its known fields at offsets `0..87`, then jumps directly to `header + 96` (`actingBlockLength`) to parse `NoFills` repeating groups—cleanly skipping the unknown 8-byte v9 extension field with zero corruption!
- **Backward Compatibility (v9 Client Receiving Older v8 Packet / PCAP Replay)**: The wire header reports `actingBlockLength = 88`, `actingVersion = 8`. When the v9 client calls `msg.newRegTimestamp`, the generated accessor checks `if (actingVersion < 9) return NULL_VALUE;` instead of reading out-of-bounds into the repeating group! Compare this zero-copy elegance with [ASCII FIX vs SBE wire latency](/reports/fix-4-4-ascii-tag-value-parsing-vs-sbe-zero-copy-wire-latency) and our [FIX, SBE & OUCH Architecture Guide](/reports/fix-protocol-sbe-ilink3-ouch-session-latency-architecture-guide).

| Schema Change Type | XML Attribute / Mechanism | Wire `version` / `schemaId` | v8 Old Client Behavior | Compatibility Verdict |
| :--- | :--- | :--- | :--- | :--- |
| **Append Field to Root Tail** | `sinceVersion="9"` + explicit `offset` | `version` `8 -> 9` (Same `schemaId`) | Skips tail via `actingBlockLength` | **100% Non-Breaking** |
| **Append Field to Group Tail** | `sinceVersion="9"` inside `<group>` | `version` `8 -> 9` (Same `schemaId`) | Skips via `group.blockLength` stride | **100% Non-Breaking** |
| **Add New Enum Bit / Constant** | New `<validValue sinceVersion="9">` | `version` `8 -> 9` | Must handle `UNKNOWN` default arm | **Safe w/ Default Switch** |
| **Change `int32` to `int64` in Place** | Modifies interior field offsets | **Increment `schemaId`!** | Would misread every subsequent byte | **Breaking (Hard Cutover)** |

## SBE Wire Compatibility Matrix Across Client & Venue Schema Versions

Understanding exactly which schema edits preserve wire compatibility versus requiring a new `schemaId` or mandatory weekend cutover prevents Aurora and NY4 Monday-open parser crashes.

```formula
Ptr_first_group = Ptr_root_start + Header.actingBlockLength
Ptr_group_elem(i) = Ptr_group_body + i * GroupHeader.actingGroupBlockLength
Val_ext_field = (Header.actingVersion >= Field_sinceVersion) ? *(T*)(Ptr_root_start + Offset) : T_NULL

Where:
 Ptr_root_start = Wire buffer byte 8 (immediately following 8-byte SBE messageHeader)
 Header.actingBlockLength = 96 bytes (v9 wire frame read by v8 client expecting 88 bytes)
 GroupHeader.actingGroupLen = 28 bytes (v9 group entry read by v8 client expecting 24 bytes)

Worked Pointer Arithmetic Verification (3 Fill Entries in v9 Frame):
 Ptr_first_group = 8 + 96 = byte offset 104 (exact start of 4B groupSizeEncoding)
 Ptr_group_elem(2) = (104 + 4) + 2 * 28 = byte offset 164 (zero desynchronization across versions!).
```

## Repeating-Group `groupSizeEncoding` Stride Safety

The identical principle protects nested repeating groups! As noted in our [zero-malloc FIX repeating-group parser analysis](/reports/fix-repeating-groups-market-data-snapshot-tag-268-allocator-design), every SBE repeating group starts with a 4-byte `groupSizeEncoding` (`uint16 blockLength`, `uint16 numInGroup`). If CME adds a 4-byte `ExecRestatement` field to each fill entry in schema v9, `group.blockLength` on the wire grows from `24` to `28`.

A v8 decoder iterating `for (i = 0; i < numInGroup; ++i)` advances its cursor by `ptr += wireGroupBlockLength` (`28`), **never** `sizeof(FillEntryV8)` (`24`)! Developers who hand-roll C structs instead of respecting `actingBlockLength` and `group.blockLength` invariably break during [CME MDP 3.0 SBE](/reports/cme-mdp-3-0-sbe-incremental-refresh-channel-arbitration-recovery) or [iLink 3 SBE](/reports/cme-ilink-3-sbe-uuid-session-negotiation-establish-state-machine) minor version bumps.

![Comparison of schema evolution overhead across Protobuf tag varints, JSON keys, SBE actingBlockLength, and raw C structs](/api/figure?type=bars&title=Schema%20Evolution%20Decode%20Cost%20%26%20Safety%20Across%20Formats&subtitle=Decode%20p99%20latency%20vs%20forward%2Fbackward%20wire%20compatibility%20%28nanoseconds%29&steps=SBE%20v8%2Fv9%20Flyweight%3A%3A185%20ns%20p99%20%20%20Full%20fwd%2Fbwd%20wire%20safety%7CRaw%20C%20Struct%20Cast%3A%3A170%20ns%20p99%20%20%20Breaks%20on%201-byte%20append!%7CProtocol%20Buffers%20v3%3A%3A1%2C120%20ns%20p99%20%20%20Varint%20tag-wire%20dispatch%7CJSON%20%2F%20REST%20String%3A%3A8%2C400%20ns%20p99%20%20%20Key%20hash%20%2B%20UTF8%20parse&metrics=SAFETY%20OVERHEAD%3A%3A%2B15%20ns%3A%3ASBE%20vs%20unsafe%20raw%20C%20struct%7CSPEEDUP%20VS%20PROTO%3A%3A6.1x%3A%3ASBE%20vs%20Google%20Protobuf%20v3%7CNULL%20SENTINEL%3A%3ASchema%20Const%3A%3AReturned%20when%20actingVer%20%3C%20N%7CBREAKING%20CHANGE%3A%3ANew%20SchemaID%3A%3ARequired%20if%20reordering%20types)

## Certification Protocol in Exchange New-Release Sandboxes

Under [CFTC](/standards/cftc), [SEC](/standards/sec), and [FCA](/standards/fca) algorithmic change-governance rules, institutional execution teams enforce three automated CI checks on SBE XML drops:

1. **Historical PCAP Regression**: Replay 6 months of v6/v7/v8 production [Aurora colocation](/engines/cme-aurora-colocation-standard) PCAPs through the newly compiled v9 binary to verify 100% `actingVersion < 9` null-sentinel handling.
2. **Synthetic Future-Version Fuzzing**: Pad `+16` random extension bytes onto every root and group `blockLength` (`actingVersion = 99`) and assert bit-identical order-book reconstruction.
3. **Risk Engine Parity**: Confirm post-upgrade fill prices feed cleanly into the [Algorithmic Kelly Allocation Calculator](/calculators/algorithmic-kelly-allocation-calculator) and explore more binary guides in the [FIX, SBE & OUCH Topic Hub](/topics/fix-protocol-sbe-ouch-session-latency).

## Frequently asked questions

### Why do handwritten C packed structs crash during CME MDP 3.0 or iLink 3 minor schema updates?

Handwritten C structs hardcode the root block size at compile time (e.g., 88 bytes). When CME increments schema version and appends an 8-byte field at byte 88, a raw struct parser reads byte 88 as the start of the repeating group header instead of jumping to byte 96 via actingBlockLength.

### Can a new variable-length string (<data>) field be inserted before an existing string in SBE?

No. Variable-length <data> elements carry only a length prefix without tag IDs and must be traversed strictly in declaration order at the very end of the SBE message. New <data> fields may only be appended after all existing <data> fields with a higher sinceVersion.

### How does an older SBE client know if a newly received message templateId is completely unknown?

If the exchange introduces an entirely new message type (e.g., TemplateId=599) in a minor release, the 6-byte framing header (SOFH messageLength on TCP or 2-byte MsgSize in MDP 3.0 UDP) tells the older client the exact total frame length so it can skip the unknown message cleanly.

### When must an exchange increment SBE schemaId instead of just incrementing version?

Incrementing schemaId is mandatory whenever any breaking structural modification occurs—such as reordering existing fields, widening an existing int32 to int64 in place, deleting a root field without padding, or changing endianness.


## Source URLs

- https://www.fixtrading.org/standards/sbe-online/
- https://www.cmegroup.com/confluence/display/EPICSANDBOX/MDP+3.0+-+Market+Data+Incremental+Refresh
- https://www.cmegroup.com/confluence/display/EPICSANDBOX/iLink+3+Binary+Order+Entry

## Citation

- APA: Marcus Thorne, CQF. (2026). SBE Schema Evolution: Forward & Backward Wire Compatibility via actingBlockLength. Terminal Ledger Desk. https://terminalledgerdesk.com/reports/sbe-schema-evolution-sinceversion-actingversion-wire-compatibility
- Canonical article: [SBE Schema Evolution: Forward & Backward Wire Compatibility via actingBlockLength](https://terminalledgerdesk.com/reports/sbe-schema-evolution-sinceversion-actingversion-wire-compatibility)
- Site research index: [Terminal Ledger Desk](https://terminalledgerdesk.com/llms-full.txt)
