Design an extensible protocol contract
04Top-level containers help older receivers. A Must-Ignore policy is a protocol design choice with precise behavior once adopted.
The I-JSON duplicate gate stops this chosen receiver before extension handling. The protocol should offer error signalling, but no wire error format is invented.
Source for this drawing: RFC 7493 · Read RFC section 4.1 ↗
New to this? Start hereA quick picture + helpful background
First, agree how to read the message.
An encoding tells a reader how to interpret bytes. A format tells it how values fit together. Correctly reading a value does not make that value trustworthy.
Helpful first, if these ideas are unfamiliar
These pictures are analogies to help you learn. The linked RFC explains the actual rules.
Terms in this drawing
Related RFCs and changes
“Updates” changes part of an earlier RFC. “Obsoletes” replaces it. This list shows selected related documents.
Ignore an unrecognized extension under its contract; still validate the message and its required meaning.
- An I-JSON message can be any JSON value. For maximum compatibility with older RFC4627 implementations that accept only top-level objects/arrays, designers SHOULD NOT use other top-level values (§4.1). A top-level number42 is not automatically invalid I-JSON; an object envelope is a recommended compatibility choice.
- A Must-Ignore policy means an unrecognized protocol element is treated as absent and MUST NOT itself be treated as an error (§4.2). A good object-based design requires top-level objects and specifies that members with unrecognized names MUST be ignored. That policy belongs to the protocol contract; it is not an unconditional rule for every arbitrary JSON application.
- In the illustrative protocol {"op":"peek","color":"teal"}, the old receiver recognizes op and ignores the newly added color member. The rest of the transaction behaves as if color were absent. This does not mean execute an unknown operation, ignore a missing required op, or let an ignored member grant permissions.
- Must-Understand has uses in some protocol designs, but can make extensions brittle. RFC7493 recommends the Must-Ignore approach described above; do not rewrite it into a universal requirement that every protocol tolerate every possible new command (§4.2).
- Receivers can reject or otherwise disregard nonconforming messages, and protocols may require rejection or not trusting such messages. Designers SHOULD provide a way for receivers to signal erroneous data (§3). The illustrated duplicate-name failure precedes the extension handler; ignoring an unknown name does not legalize duplicate names or malformed input. No particular error status, field or transport is prescribed.
Offline illustrative messages and bounded helpers, not a production parser, full calendar validator or authentication protocol. Reported errata are not adopted as verified corrections.
Read the RFC section ↗