API contract practical

Protobuf JSON Enum

Try the old reader before deploying a new status. A parser can return successfully while the message it forwards has already changed.

Executed runtime
Python 3.14.7, protobuf 7.36.2, upb; proto3 open enums
Same four fixtures
Binary retained all 4; strict JSON names rejected all 4
Accepted is not retained
Ignoring unknown JSON names changed all 4 fixtures
Numeric limit
Integer enum output retained 3 of 4; the new object field was lost
A courier points to a missing star-shaped parcel in a returned tray. A clerk uses an older catalog showing only cubes; the star sits in a basket.
Story illustration of a translator dropping an unfamiliar item while keeping the items in its older catalog.

Start with the value that disappears

Send {"status":"STATUS_PAUSED"} to a reader whose enum knows only STATUS_UNSPECIFIED and STATUS_READY. In the executed Python lab, the normal parser raised ParseError. With ignore_unknown_fields=True, parsing succeeded, but forwarding the message produced {}. A newer reader then saw status 0. The future state had disappeared.

Use that as the first regression check for a JSON gateway, queue adapter or read-modify-write service. Ask two questions: did the old reader accept the message, and did the next reader recover the same information? Those are separate assertions.

The lab below runs the actual Python Protobuf runtime through two isolated schema versions. It compares four transport policies on four fixtures. The result concerns these round trips, not network latency, throughput or every Protobuf language implementation.

Distinguish the name from the number

Our old schema defines status 0 and 1. The new schema adds STATUS_PAUSED = 2. It also adds a separate string field, memo, so the test can distinguish an unknown enum value inside a known field from an entirely unknown field.

The newer fixture schema; the older version lacks STATUS_PAUSED and memo.
syntax = "proto3";
package relay;
enum Status {
  STATUS_UNSPECIFIED = 0;
  STATUS_READY = 1;
  STATUS_PAUSED = 2; // New in version 2.
}
message Job {
  Status status = 1;
  repeated Status history = 2;
  map<string, Status> statuses = 3;
  string memo = 4; // New in version 2.
}

By default, a known enum value is printed as its symbolic JSON name. The ProtoJSON format also requires parsers to accept enum integers. A numeric token such as 2 and an unfamiliar name such as "STATUS_PAUSED" therefore reach different parsing paths. A number does not need the old descriptor to know its future spelling.

This is Protobuf JSON mapping, not ordinary serialization of an arbitrary Python dictionary. In the test, MessageToDict produces a ProtoJSON-compatible object and ParseDict consumes it. The intermediate dictionary is the JSON representation. No HTTP server or separate JSON serializer is involved.

Compare four routes on four fixtures

Each fixture starts as a new-schema message, crosses an old-schema reader and returns to a new-schema reader. "Retained" means Protobuf message equality with the starting message, including the future value or field. "Changed" means parsing completed but equality failed. "Rejected" means the old parser raised ParseError before forwarding.

Observed outcomes in protobuf 7.36.2: each cell is one executed round trip.
FixtureBinaryNames, strictNames, ignoreNumbers, ignore
status = 2RetainedRejectedChanged to 0Retained
history = [1, 2]RetainedRejectedChanged to [1]Retained
Map has future = 2RetainedRejectedFuture entry removedRetained
New memo fieldRetainedRejectedMemo removedMemo removed
Of four identical fixtures per route, binary preserved four. Strict JSON names rejected four. Ignored JSON names changed four. Ignored JSON numbers preserved three and changed one.
Counts from the saved 16-case runtime output. The denominator is four fixtures per route. These counts are not a reliability score. View full-size figure.

Strict rejection is visible and can be handled before a message is forwarded. Silent changes need a different test. Counting successful parses would rate the lenient name route as successful in all four cases, even though it retained none of the four future-information fixtures.

Inspect what the ignore option removes

The singular status became its implicit default. The repeated enum ["STATUS_READY", "STATUS_PAUSED"] became ["STATUS_READY"]. In the map, the future key vanished while the known key remained. The new memo property vanished too. These are four different shapes of information loss under the same lenient setting.

Our map uses string keys and enum values. It does not use an enum as a map key: that is outside the schema shown here. For the repeated field, checking only the first retained element would miss the shortened list. For the map, checking only that parsing returned a nonempty object would miss the missing entry.

Core comparison from the downloadable lab, after its old and new message types are created.
incoming = {"history": ["STATUS_READY", "STATUS_PAUSED"]}
old_message = json_format.ParseDict(
    incoming, old(), ignore_unknown_fields=True
)
forwarded = json_format.MessageToDict(old_message)
assert forwarded == {"history": ["STATUS_READY"]}

The release-tagged Python parser source contains the enum-name conversion and skip handling exercised by these cases. Treat the option as permission to discard information. It is appropriate only when the receiving contract explicitly allows that discard, such as a projection that intentionally ignores fields it does not display.

Emit numbers with a narrow promise

On the new-schema emitter, use_integers_for_enums=True changed "STATUS_PAUSED" to 2, including enum values inside the repeated field and map. All three enum fixtures survived the old open-enum reader. The Python JSON API documents the emission switch. The downloadable cases verify its effect for this runtime.

An old reader rejects the unfamiliar name in strict mode, skips it in ignore mode and retains integer 2 in a proto3 open-enum field.
Three paths for the same future status. The observed scalar lenient result is default 0 and an omitted JSON field. View full-size figure.

Changing only the relay printer is too late if its parser has already discarded an unfamiliar symbolic name. Set the emitter policy before sending new values across an old boundary. Review every relevant producer and JSON bridge, not just one serializer call.

An old reader that first receives binary status 2 already holds an unknown number in its open-enum field. In a separate boundary check, its default JSON printer emitted {"status":2} without needing the integer-output switch. That differs from receiving the unrecognized string name in JSON. Trace where the value first crosses the descriptor boundary.

A number does not save an unknown field

The numeric route still lost memo="keep-me". That field was not in the old schema, so no enum-output option could preserve it. In the binary relay, the old reader retained the unknown field and the new reader recovered the string. Passing the same old message through MessageToDict removed the memo from the JSON representation.

The proto3 guide on unknown fields describes binary retention and warns about JSON conversion and field-by-field message reconstruction. A relay that must retain future fields should preserve the binary message, use a supported message copy operation or explicitly carry the original payload under a reviewed contract. Merely rebuilding a message from the fields the old code recognizes discards its unknown-field set.

An opaque payload is useful only if downstream systems actually forward it and the application handles it under its existing access, size and retention rules. Do not silently promise that a JSON proxy preserves all future fields when its typed old-schema decoder cannot represent them.

Check the enum kind and runtime

The enum behavior reference separates open and closed enums. An open enum can store an unrecognized integer in the field. A closed enum treats that integer as an unknown field value instead. Field access can then expose an unset field or default. That distinction changes what a relay and its application code can observe.

This lab declares syntax = "proto3" in both descriptors and tests open enums. It does not establish proto2 behavior, mixed imports, Editions feature settings or the behavior of Java, Go, C# and other runtimes. The reference lists language-specific conformance differences. Verify the actual descriptor and deployed runtime before transferring the Python result to another stack.

Keep the raw numeric value when an API supplies a separate numeric accessor. A generated sentinel such as Java UNRECOGNIZED is a signal that the application does not know the symbol. It should not become a new wire value that replaces the original integer. This is a documentation boundary to test in that language, not a second executed result from this Python lab.

Keep default, null and unknown distinct

STATUS_UNSPECIFIED = 0 is a declared schema value. The future number 2 is a different value even when the old application does not understand it. Mapping both to "ready" would erase that distinction and could trigger work the sender never requested.

For the implicit-presence scalar in this fixture, 0 was omitted from JSON output. That is why a dropped unknown name appeared as {} rather than as an explicit zero. An extra executed check parsed {"status":null} into a message initially holding status 1. The resulting message held 0 and printed {}. A null token is not a request to preserve an unfamiliar enum name.

This fixture has no optional status, so it does not distinguish an explicitly present zero from an unset scalar. Add an optional-field fixture if your product depends on presence. The ProtoJSON null rules and the field's presence semantics need to be reviewed together.

Deploy readers before new names

  1. Inventory every JSON reader between the producer and final consumer, including stored payloads, replay jobs and rollback versions. Mark whether each boundary rejects or discards unknown information.
  2. Deploy readers that recognize the new enum name before a producer emits it. If numeric enum output is the chosen contract, verify that policy on every relevant emitter and verify open-enum numeric handling on the readers.
  3. Keep an older reader in the test matrix. Feed the new singular value, repeated value, map value and an added object field through the full relay path. Compare recovered values as well as parser outcomes.
  4. Enable new writes only after the required reader population is ready. Retain tests for old stored messages and the versions that can still be rolled back.

Renaming a symbol also affects JSON even when its number stays fixed. For an alias transition, the schema best practices place the new alias after the old one while readers learn both names. Only later does reordering change the emitted name. Keep the old spelling until the remaining readers, stored data and rollback policy permit its removal.

Reserve deleted enum numbers and names against reuse. Do not use a number change as a quick JSON migration fix: the binary field still assigns meaning by number. These rollout checks complement the broader event schema evolution matrix, which owns replay promises and consumer-version planning.

Separate transport from business decisions

Retaining 2 does not teach the old service what PAUSED means. A pure relay may forward an unrecognized number. A service making an irreversible business decision should have an explicit policy for a status it cannot interpret: reject that action, defer it or route it to a controlled exception path. It should not infer authorization or completion from successful parsing.

Keep transport preservation tests separate from application validation tests. The lab checks that the old descriptor retains an unfamiliar number and separately asserts that the number is outside its recognized set. Your product test must state which action, if any, is allowed for that case.

For a user-facing projection, displaying "unrecognized status" may be acceptable. For a read-modify-write relay, writing a default back to storage can overwrite the sender's future state. Record the boundary's role before choosing the ignore option.

Run the Python relay lab

Download the complete experiment and saved JSON results. The script builds old and new message types from descriptors in separate pools, so it needs no protoc executable or generated application code. Run it in an isolated environment:

Install the exact tested runtime, then run the saved experiment locally.
python3 -m venv .venv
.venv/bin/python -m pip install protobuf==7.36.2
.venv/bin/python experiment.py > actual.json

The recorded run used Python 3.14.7, Protobuf 7.36.2 and the upb implementation. Two runs produced byte-identical JSON output. The 16 main cases contain four routes times four fixtures. Separate assertions check binary-to-JSON behavior, null and whether the old application recognizes the future number. The script makes no network requests after dependency installation and measures no timing.

For your own regression, change the descriptors to the actual old and new schema versions. Preserve the four fixture shapes and the two assertions: whether the reader accepts the payload, and whether the final reader recovers the required values. Add a failure when either outcome contradicts the contract you intend to ship.

Check neighboring JSON contracts separately

Enum-name compatibility does not settle numeric identifier precision. For that problem, use the separate large integer JSON round-trip cases. A patch endpoint also needs a defined difference between omission and clearing. The JSON Merge Patch null and omitted tests cover that update contract.

Keep those concerns in their own fixtures. The acceptance criterion for this relay is concrete: the old reader must either reject unsupported information visibly or forward the values the next reader needs. A successful parse alone does not satisfy that criterion.

Sources

Documentation checked .

  1. ProtoJSON format and wire safety
  2. Open and closed enum behavior
  3. Python json_format API
  4. Proto3 unknown fields and compatibility
  5. Protobuf schema best practices
  6. Tested release: Python JSON parser source

Continue the conversation

Comments (0)

    Leave a comment

    Your name and comment stay in this page and are cleared after the spam check.

    10–2,000 characters. Keep the discussion relevant to this article.

    Spam protection verification
    Spam protection loads when you begin the form.

    JavaScript is required to use this form and its spam protection.