idnits 2.17.00 (12 Aug 2021) /tmp/idnits17065/draft-ietf-json-i-json-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 27, 2015) is 2664 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE754' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Bray, Ed. 3 Internet-Draft Textuality Services 4 Intended status: Standards Track January 27, 2015 5 Expires: July 31, 2015 7 The I-JSON Message Format 8 draft-ietf-json-i-json-06 10 Abstract 12 I-JSON is a restricted profile of JSON designed to maximize 13 interoperability and increase confidence that software can process it 14 successfully with predictable results. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on July 31, 2015. 33 Copyright Notice 35 Copyright (c) 2015 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 2 53 2. I-JSON Messages . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Encoding and Characters . . . . . . . . . . . . . . . . . 3 55 2.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.3. Object constraints . . . . . . . . . . . . . . . . . . . 3 57 3. Software Behavior . . . . . . . . . . . . . . . . . . . . . . 4 58 4. Protocol-design Recommendations . . . . . . . . . . . . . . . 4 59 4.1. Top-level Constructs . . . . . . . . . . . . . . . . . . 4 60 4.2. Must-ignore Policy . . . . . . . . . . . . . . . . . . . 4 61 4.3. Time and Date Handling . . . . . . . . . . . . . . . . . 5 62 4.4. Binary Data . . . . . . . . . . . . . . . . . . . . . . . 5 63 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 64 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 65 7. Normative References . . . . . . . . . . . . . . . . . . . . 5 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 68 1. Introduction 70 RFC 7159 describes the JSON data interchange format, which is widely 71 used in Internet protocols. For historical reasons, that 72 specification allows the use of language idioms and text encoding 73 patterns which are likely to lead to interoperability problems and 74 software breakage, particularly when a program receiving JSON data 75 uses automated software to map it into native programming-language 76 structures or database records. RFC 7159 describes practices which 77 may be used to avoid these interoperability problems. 79 This document specifies I-JSON, short for "Internet JSON". The unit 80 of definition is the "I-JSON message". I-JSON messages are also 81 "JSON texts" as defined in RFC 7159 but with certain extra 82 constraints which enforce the good interoperability practices 83 described in that specification. 85 1.1. Terminology 87 The terms "object", "member", "array", "number", "name", and "string" 88 in this document are to be interpreted as described in RFC 7159 89 [RFC7159]. 91 1.2. Requirements Language 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 95 document are to be interpreted as described in RFC 2119 [RFC2119]. 97 2. I-JSON Messages 99 An I-JSON message is a JSON text, as defined by RFC 7159. 101 2.1. Encoding and Characters 103 I-JSON messages MUST be encoded using UTF-8 [RFC3629]. 105 Object member names, and string values in arrays and object members, 106 MUST NOT include code points which identify Surrogates or 107 Noncharacters [UNICODE] (Section 2.4). 109 This applies both to characters encoded directly in UTF-8 and to 110 those which are escaped; thus, "\uDEAD" is invalid because it is an 111 unpaired surrogate, while "\uD800\uDEAD" would be legal. 113 2.2. Numbers 115 Software which implements IEEE 754-2008 binary64 (double precision) 116 numbers [IEEE754] is generally available and widely used. 117 Implementations which generate I-JSON messages cannot assume that 118 receiving implementations can process numeric values with greater 119 magnitude or precision than provided by those numbers. I-JSON 120 messages SHOULD NOT include numbers which express greater magnitude 121 or precision than an IEEE 754 double precision number provides, for 122 example 1E400 or 3.141592653589793238462643383279. 124 An I-JSON sender cannot expect a receiver to treat an integer whose 125 absolute value is greater than 9007199254740991 (i.e., that is 126 outside the range [-(2**53)+1, (2**53)-1]) as an exact value. 128 For applications which require the exact interchange of numbers with 129 greater magnitude or precision, it is RECOMMENDED to encode them in 130 JSON string values. This requires that the receiving program 131 understand the intended semantic of the value. An example would be 132 64-bit integers, even though modern hardware can deal with them, 133 because of the limited scope of JavaScript numbers. 135 2.3. Object constraints 137 Objects in I-JSON messages MUST NOT have members with duplicate 138 names. In this context, "duplicate" means that the names, after 139 processing any escaped characters, are identical sequences of Unicode 140 characters. 142 The order of object members in an I-JSON message does not change the 143 meaning of an I-JSON message. A receiving implementation MAY treat 144 two I-JSON messages as equivalent if they differ only in the order of 145 the object members. 147 3. Software Behavior 149 A major advantage of using I-JSON is that receivers can avoid 150 ambiguous semantics in the JSON messages they receive. This allows 151 receivers to reject or otherwise disregard messages which do not 152 conform to the requirements in this document for I-JSON messages. 153 Protocols that use I-JSON message can be written so that receiving 154 implementations are required to reject (or, as in the case of 155 security protocols, not trust) messages that do not satisfy the 156 constraints of I-JSON. 158 Designers of protocols which use I-JSON messages SHOULD provide a 159 way, in this case, for the receiver of the erroneous data to signal 160 the problem to the sender. 162 4. Protocol-design Recommendations 164 I-JSON is designed for use in Internet protocols. The following 165 recommendations apply to the use of I-JSON in such protocols. 167 4.1. Top-level Constructs 169 An I-JSON message can be any JSON value. However, there are software 170 implementations, coded to the older [RFC4627] specification, which 171 only accept JSON objects or JSON arrays at the top level of JSON 172 texts. For maximum interoperability with such implementations, 173 protocol designers SHOULD NOT use top-level JSON texts which are 174 neither objects nor arrays. 176 4.2. Must-ignore Policy 178 It is frequently the case that changes to protocols are required 179 after they have been put in production. Protocols which allow the 180 introduction of new protocol elements in a way that does not disrupt 181 the operation of existing software have proven advantageous in 182 practice. 184 This can be referred to as a "Must-Ignore" policy, meaning that when 185 an implementation encounters a protocol element which it does not 186 recognize, it should treat the rest of the protocol transaction as if 187 the new element simply did not appear, and in particular MUST NOT 188 treat this as an error condition. The converse "Must-Understand" 189 policy does not tolerate the introduction of new protocol elements, 190 and while this has proven necessary in certain protocol designs, in 191 general it has been found to be overly restrictive and brittle. 193 A good way to support the use of Must-Ignore in I-JSON protocol 194 designs is to require that top-level protocol elements must be JSON 195 objects, and to specify that members whose names are unrecognized 196 MUST be ignored. 198 4.3. Time and Date Handling 200 Protocols often contain data items which are designed to contain 201 timestamps or time durations. It is RECOMMENDED that all such data 202 items be expressed as string values in ISO 8601 format, as specified 203 in [RFC3339], with the additional restrictions that uppercase rather 204 than lowercase letters be used, that the timezone be included not 205 defaulted, and that optional trailing seconds be included even when 206 their value is "00". It is also RECOMMENDED that all data items 207 containing time durations conform to the "duration" production in 208 Appendix A of RFC3339, with the same additional restrictions. 210 4.4. Binary Data 212 When it is required that an I-JSON protocol element contain arbitrary 213 binary data, it is RECOMMENDED that this data be encoded in a string 214 value in base64url; see Section 5 of [RFC4648]. 216 5. Acknowledgements 218 I-JSON is entirely dependent on the design of JSON, largely due to 219 Douglas Crockford. The specifics were strongly influenced by the 220 contributors to the design of RFC 7159 on the IETF JSON Working 221 Group. 223 6. Security Considerations 225 All the security considerations which apply to JSON (see RFC 7159) 226 apply to I-JSON. There are no additional security considerations 227 specific to I-JSON. 229 Since I-JSON forbids the use of certain JSON idioms that can lead to 230 unpredictable behavior in receiving software, it may prove a more 231 secure basis for Internet protocols, and may be a good choice for 232 protocol designers with special security needs. 234 7. Normative References 236 [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", 2008, 237 . 239 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 240 Requirement Levels", BCP 14, RFC 2119, March 1997. 242 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 243 Internet: Timestamps", RFC 3339, July 2002. 245 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 246 10646", STD 63, RFC 3629, November 2003. 248 [RFC4627] Crockford, D., "The application/json Media Type for 249 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 251 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 252 Encodings", RFC 4648, October 2006. 254 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 255 Interchange Format", RFC 7159, March 2014. 257 [UNICODE] The Unicode Consortium, "The Unicode Standard", 2003-, 258 . 260 Note that this reference is to the latest version of 261 Unicode, rather than to a specific release. It is not 262 expected that future changes in the UNICODE specification 263 will affect the referenced classifications. 265 Author's Address 267 Tim Bray (editor) 268 Textuality Services 270 Email: tbray@textuality.com 271 URI: https://www.tbray.org/