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/