Visual RFC.
ALL RFCs / RFC 7493
Read the RFC ↗
RFC 7493 / Internet JSON interoperability

Design an extensible protocol contract

04

Top-level containers help older receivers. A Must-Ignore policy is a protocol design choice with precise behavior once adopted.

RFC 7493 · § 4.1EXAMPLE
4 / 4
Design an extensible protocol contractA duplicate color name stops the chosen receiver at validation before the ignore handler; no invented error field, status or delivery follows.An explicit protocol can tolerate extensions{"op":"peek","color":1,"color":2}Repeated color violates I-JSON constraintsValidation before extension handlingIgnoring a name does not legalize duplicationProtocol SHOULD offer error signallingAdopted contract matters · validate before interpreting
04
Keep validation before extensions

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 ↗

Protocol participantThreat or exceptionProtocol controlSimplified drawings · precise section references
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.

Related RFCs and changes

“Updates” changes part of an earlier RFC. “Obsoletes” replaces it. This list shows selected related documents.

KEY POINT

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.
DETAILS

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 ↗

All chapters in RFC 7493

Drawing view

Scroll the drawing to see every part. Playback controls stay above it.

RFC 9700 / CHAPTERS

Chapters

For full details, tables, algorithms, and exceptions, read the original RFC.

RFC status and corrections ↗