How Should a Protocol Handle Unknown Fields?
From the earlier reference collection. Read the current software blog.
A protocol should make explicit whether unknown fields are ignored, retained, or rejected, because the safe rule depends on context.
Unknown does not mean meaningless
A client may receive a field that did not exist when it was written. The field could be a harmless addition, a new display hint, or a security-sensitive instruction. If a protocol says nothing, different implementations may make incompatible assumptions: one ignores it, another rejects the whole message, and a third preserves it during a read-and-write cycle.
Compatibility therefore depends on a specified rule. For ordinary optional metadata, ignoring an unrecognized field can let older clients continue to process newer messages. For a command that changes permissions or financial state, silently ignoring an unknown instruction might cause the sender and receiver to believe different outcomes occurred.
Choose a rule for each context
A schema should say whether unknown fields are ignored, preserved, or rejected in each message context. “Ignore” means the receiver does not apply the unknown value. “Preserve” means it retains the value when it forwards or serializes the object again. “Reject” means processing fails with a defined error. These behaviors are distinct: a system can ignore a field for its own behavior yet preserve it when acting as a relay.
For example, an older profile editor may recognize display_name but not accent_color. It can update the name and preserve the color while saving the profile, preventing data loss. By contrast, an older payment processor receiving an unknown settlement mode might reject the request, because proceeding with a guessed interpretation could be unsafe.
Consider validation and security
Specify how unknown fields interact with duplicate names, field limits, and required fields. A parser that accepts arbitrary extras can be exposed to oversized or deeply nested input unless the protocol bounds message size and structure. Also state whether unknown fields can override recognized values through aliases or alternate encodings; ambiguous interpretation creates room for inconsistent validation.
For extensible messages, it can help to reserve a designated extension map or namespace. That keeps additions identifiable and gives implementations a place to retain data they do not understand. A security-sensitive receiver should reject extensions that affect authorization or execution unless it explicitly supports their meaning.
Test older and newer participants
A useful compatibility test sends a newer message to an older client, changes a known field while retaining an unknown one, and then checks what gets written back. Test a second case where an unknown field appears in a command with side effects. The results should match the documented policy, not accidental parser behavior.
A clear rule lets protocol authors evolve messages while giving implementers predictable choices. The right policy may differ between informational records and actionable requests; the specification should name that difference so neither data loss nor unintended execution is left to chance.