Protobuf Compatibility and Message Versioning

_Locale: en-US · Lesson: DAT-015 · Public order: 72_

Outcome and working artifact

This lesson produces a Protobuf Compatibility Change Record v1: a decision artifact that separates observations, assumptions, limits, and required evidence. The goal is a transferable model, not memorized tool names.

می‌تواند «Protobuf Compatibility و Message Versioning» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.

Boundary model

A .proto file can compile while an evolution still damages old readers, new readers, stored messages, or ProtoJSON clients. In Protobuf, field numbers are wire identities. Compatibility therefore requires a directional old/new test, reservation of deleted identifiers, and separate judgment for binary and JSON representations.

Keep three labels throughout the work: observed, bounded inference, and needs verification. When evidence is unavailable, record unknown. A product name or a passing happy path is not a substitute for evidence.

1. Field numbers are identities

A field name can change without changing binary identity, but changing or reusing a number changes how bytes are interpreted. Treat numbers as durable contract assets.

2. Reserve what you delete

When a field is removed, reserve its number and usually its name where relevant. This prevents a future author from accidentally reusing an identity that old data still carries.

3. Compatibility is directional

Test old writer→new reader and new writer→old reader separately. Unknown fields and default behavior can make one direction acceptable while another loses information.

4. Type changes need wire and value analysis

Some types share a wire encoding but are not automatically safe for every value. Golden boundary messages are needed, especially for narrowing or signedness changes.

5. ProtoJSON is a different boundary

JSON field names and representation rules create risks not visible in binary wire tests. If JSON is persisted or exchanged, classify it independently.

Five-step method

1. Inventory every existing field number, type, cardinality, oneof membership, and JSON name.
2. Describe the proposed diff and classify additions, deletions, renames, number changes, and type changes separately.
3. Run old-writer/new-reader and new-writer/old-reader tests with representative and boundary messages.
4. Reserve deleted numbers and names, then run a deliberate reuse mutation that must fail review.
5. Repeat the judgment for ProtoJSON when JSON storage or exchange exists; record data-loss and residual limits.

Worked case

OrderCreated v1 has order_id = 1, customer_email = 2, and total_cents = 3. Version 2 adds optional currency = 4 and removes email. The safe candidate reserves number 2 and its name. Golden binary tests run in both directions; the old reader ignores field 4, so currency information is not preserved in that direction and the record says so. A mutation reuses number 2 for customer_phone and is rejected even though both schemas compile. ProtoJSON clients are reviewed separately because field-name changes can break persisted JSON.

Decision and evidence matrix

Failure probes and repair

• If protoc compiles both schemas, the change is automatically backward and forward compatible.
• Deleted field numbers may be safely reused after enough time.
• Binary wire compatibility implies ProtoJSON compatibility.
• Changing a field number is a harmless rename.

For each statement, narrow the claim, create a counterexample, and name the observation that could confirm or reject it.

Transfer challenge

Change the scenario so that one assumption in the worked case no longer holds. Rebuild the Protobuf Compatibility Change Record v1 without copying the earlier decision, then explain what changed in the input and what stayed stable in the decision rule.

What this does not prove

This lesson does not claim certification, production guarantees, or coverage of every implementation. Its conclusion is valid only within the scenario boundary, dated sources, and recorded observations.

Self-check

• [ ] Did I separate responsibilities from framework or tool names?
• [ ] Did I state at least one failure probe and its predicted observable?
• [ ] Are fact, inference, and design choice visibly separated?
• [ ] Did I record non-claims and missing evidence?
• [ ] Did I complete transfer in a changed context without a prepared answer?

Sources and freshness boundary

Sources were reviewed for the frozen Bible as of 2026-09-19. A review_due date triggers a versioned requalification; it does not authorize silent in-place edits.

• PROTO3-GUIDE — Official field-number, deletion/reservation and message-update compatibility guidance. (https://protobuf.dev/programming-guides/proto3/; review: 2026-10-17)
• PROTOJSON — Official ProtoJSON format and compatibility considerations. (https://protobuf.dev/programming-guides/json/; review: 2026-10-17)