RFC 7493

The I-JSON Message Format

📅 published March 2015, from ietf

RFC 7493: The I-JSON Message Format 💖

Okay bestie, first the vibe check 🎀. This is RFC 7493, titled "The I-JSON Message Format". It was edited by T. Bray, Ed. (Tim Bray) at Textuality Services, and it came out in March 2015. It's a Standards Track document, which means it's an official Internet standard, not just a suggestion 👑. The ISSN is 2070-1721. The title block doesn't list anything it obsoletes or updates, so it stands on its own ✨.

Okay the table of contents is next, and I'm keeping it exactly as it is 🧚

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
  1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   2
  1.2.  Requirements Language . . . . . . . . . . . . . . . . . .   2
2.  I-JSON Messages . . . . . . . . . . . . . . . . . . . . . . .   3
  2.1.  Encoding and Characters . . . . . . . . . . . . . . . . .   3
  2.2.  Numbers . . . . . . . . . . . . . . . . . . . . . . . . .   3
  2.3.  Object Constraints  . . . . . . . . . . . . . . . . . . .   3
3.  Software Behavior . . . . . . . . . . . . . . . . . . . . . .   4
4.  Recommendations for Protocol Design . . . . . . . . . . . . .   4
  4.1.  Top-Level Constructs  . . . . . . . . . . . . . . . . . .   4
  4.2.  Must-Ignore Policy  . . . . . . . . . . . . . . . . . . .   4
  4.3.  Time and Date Handling  . . . . . . . . . . . . . . . . .   5
  4.4.  Binary Data . . . . . . . . . . . . . . . . . . . . . . .   5
5.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
6.  Normative References  . . . . . . . . . . . . . . . . . . . .   5
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   6
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

Abstract

Okay, so I-JSON (short for "Internet JSON") is a restricted profile of JSON. Its whole job is to maximize interoperability and make software way more likely to process it successfully with predictable results 💅✨.

Status of This Memo

This is an Internet Standards Track document 👑.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 5741 🦋.

For the current status of this document, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc7493 🌸.

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved 🔒.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the date this document was published. Please read these carefully, because they're the rules for what you're allowed to do and not do with this document 📜. Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License 🎀.

1. Introduction 🌈

RFC 7159 describes the JSON data interchange format, and it's used all over Internet protocols. For historical reasons, that spec lets people use language idioms and text encoding patterns that can cause interoperability problems and software breakage. This gets especially messy when a program receiving JSON uses automated software to map it into native programming-language structures or database records 💀. RFC 7159 describes practices that may be used to avoid these interoperability problems 🫶.

This document specifies I-JSON, short for "Internet JSON". The unit of definition is the "I-JSON message". I-JSON messages are also "JSON texts" as defined in RFC 7159, but with some extra constraints that enforce the good interoperability practices from that spec ✨.

1.1. Terminology 🧸

The terms "object", "member", "array", "number", "name", and "string" in this document are to be interpreted as described in RFC 7159 [RFC7159].

1.2. Requirements Language 💜

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 📚.

2. I-JSON Messages 💖

An I-JSON message is a JSON text, as defined by RFC 7159 🍓.

2.1. Encoding and Characters 🔤

I-JSON messages MUST be encoded using UTF-8 [RFC3629]. No skipping this, periodt 💅.

Object member names, and string values in arrays and object members, MUST NOT include code points that identify Surrogates or Noncharacters as defined by [UNICODE] 🙈.

This applies both to characters encoded directly in UTF-8 and to characters that are escaped. So "\uDEAD" is invalid because it's an unpaired surrogate, while "\uD800\uDEAD" would be legal 😭.

2.2. Numbers 🔢

Software that implements IEEE 754-2008 binary64 (double precision) numbers [IEEE754] is generally available and widely used 💅. Implementations that generate I-JSON messages can't assume that receiving implementations can handle numeric values with greater magnitude or precision than those numbers provide. I-JSON messages SHOULD NOT include numbers that express greater magnitude or precision than an IEEE 754 double precision number provides, for example 1E400 or 3.141592653589793238462643383279 💀.

An I-JSON sender can't expect a receiver to treat an integer as an exact value if its absolute value is greater than 9007199254740991 (i.e., if it's outside the range [-(2**53)+1, (2**53)-1]) 🙈.

For applications that need exact interchange of numbers with greater magnitude or precision, it is RECOMMENDED to encode them in JSON string values 🎀. This requires that the receiving program understand the intended semantic of the value. An example would be 64-bit integers, even though modern hardware can deal with them, because of the limited scope of JavaScript numbers 🧚.

2.3. Object Constraints 🧱

Objects in I-JSON messages MUST NOT have members with duplicate names 🚫. In this context, "duplicate" means that the names, after processing any escaped characters, are identical sequences of Unicode characters.

The order of object members in an I-JSON message doesn't change its meaning. A receiving implementation MAY treat two I-JSON messages as equivalent if they differ only in the order of the object members 🦋.

3. Software Behavior 🌸

A major perk of I-JSON is that receivers can avoid ambiguous semantics in the JSON messages they get. This means receivers can reject or otherwise ignore messages that don't meet the I-JSON requirements in this document 👑. Protocols that use I-JSON messages can be written so that receiving implementations are required to reject (or, in the case of security protocols, not trust) messages that don't satisfy I-JSON constraints 🔥.

Designers of protocols that use I-JSON messages SHOULD provide a way, in this case, for the receiver of the erroneous data to signal the problem to the sender 💌.

4. Recommendations for Protocol Design 🎀

I-JSON is designed for Internet protocols, so the following recommendations apply when you use it in those 🌈.

4.1. Top-Level Constructs 🧩

An I-JSON message can be any JSON value. BUT, there are software implementations, coded to the older specification [RFC4627], that only accept JSON objects or JSON arrays at the top level of JSON texts 🙃. For maximum interoperability with those implementations, protocol designers SHOULD NOT use top-level JSON texts that are neither objects nor arrays 🫶.

4.2. Must-Ignore Policy 🛡️

Protocols often need changes after they've gone into production. Protocols that let you add new protocol elements without disrupting existing software have proven really useful in practice ✨.

This can be called a "Must-Ignore" policy. When an implementation runs into a protocol element it doesn't recognize, it should treat the rest of the protocol transaction as if the new element simply didn't appear. In particular, the implementation MUST NOT treat this as an error condition 🙌. The converse, the "Must-Understand" policy, doesn't tolerate new protocol elements at all. That has been necessary in some protocol designs, but in general it's been found to be too restrictive and brittle 😩.

A good way to support Must-Ignore in I-JSON protocol designs is to require that top-level protocol elements must be JSON objects, and to specify that members whose names are unrecognized MUST be ignored 🧁.

4.3. Time and Date Handling ⏰

Protocols often have data items meant to hold timestamps or time durations. It is RECOMMENDED that all of these data items be expressed as string values in ISO 8601 format, as specified in [RFC3339]. There are a few extra rules: uppercase letters rather than lowercase letters are used, the timezone is included and not defaulted, and optional trailing seconds are included even when their value is "00" 🕐. It is also RECOMMENDED that all data items containing time durations conform to the "duration" production in Appendix A of RFC 3339, with the same additional restrictions 🌙.

4.4. Binary Data 🧃

When an I-JSON protocol element is required to contain arbitrary binary data, it is RECOMMENDED that this data be encoded in a string value in base64url. See Section 5 of [RFC4648] 💫.

5. Security Considerations 🚨

All the security considerations that apply to JSON (see RFC 7159) apply to I-JSON too. There are no additional security considerations specific to I-JSON 🔐.

Okay, this part is actually important. Since I-JSON forbids certain JSON idioms that can lead to unpredictable behavior in receiving software, it may prove to be a more secure basis for Internet protocols. It may be a great choice for protocol designers with special security needs 🛡️💜.

6. Normative References 📚

Acknowledgements 🫶

I-JSON depends entirely on the design of JSON, and that's largely thanks to Douglas Crockford 👑. The specifics were strongly influenced by the contributors to the design of RFC 7159 in the IETF JSON Working Group 💖.

Author's Address 📮

Tim Bray (editor) Textuality Services

EMail: tbray@textuality.com URI: https://www.tbray.org/

📦 where this page comes from