RFC6901 JSON Pointer implementation in OCaml using jsont
anil.recoil.org
1
2
3
4
5
6
7Internet Engineering Task Force (IETF) P. Bryan, Ed.
8Request for Comments: 6901 Salesforce.com
9Category: Standards Track K. Zyp
10ISSN: 2070-1721 SitePen (USA)
11 M. Nottingham, Ed.
12 Akamai
13 April 2013
14
15
16 JavaScript Object Notation (JSON) Pointer
17
18Abstract
19
20 JSON Pointer defines a string syntax for identifying a specific value
21 within a JavaScript Object Notation (JSON) document.
22
23Status of This Memo
24
25 This is an Internet Standards Track document.
26
27 This document is a product of the Internet Engineering Task Force
28 (IETF). It represents the consensus of the IETF community. It has
29 received public review and has been approved for publication by the
30 Internet Engineering Steering Group (IESG). Further information on
31 Internet Standards is available in Section 2 of RFC 5741.
32
33 Information about the current status of this document, any errata,
34 and how to provide feedback on it may be obtained at
35 http://www.rfc-editor.org/info/rfc6901.
36
37Copyright Notice
38
39 Copyright (c) 2013 IETF Trust and the persons identified as the
40 document authors. All rights reserved.
41
42 This document is subject to BCP 78 and the IETF Trust's Legal
43 Provisions Relating to IETF Documents
44 (http://trustee.ietf.org/license-info) in effect on the date of
45 publication of this document. Please review these documents
46 carefully, as they describe your rights and restrictions with respect
47 to this document. Code Components extracted from this document must
48 include Simplified BSD License text as described in Section 4.e of
49 the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.
51
52
53
54
55
56
57
58Bryan, et al. Standards Track [Page 1]
59
60RFC 6901 JSON Pointer April 2013
61
62
63Table of Contents
64
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
66 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 2
67 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
68 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3
69 5. JSON String Representation . . . . . . . . . . . . . . . . . . 4
70 6. URI Fragment Identifier Representation . . . . . . . . . . . . 5
71 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6
72 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
73 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
74 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
75 10.1. Normative References . . . . . . . . . . . . . . . . . . . 7
76 10.2. Informative References . . . . . . . . . . . . . . . . . . 7
77
781. Introduction
79
80 This specification defines JSON Pointer, a string syntax for
81 identifying a specific value within a JavaScript Object Notation
82 (JSON) document [RFC4627]. JSON Pointer is intended to be easily
83 expressed in JSON string values as well as Uniform Resource
84 Identifier (URI) [RFC3986] fragment identifiers.
85
862. Conventions
87
88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
90 document are to be interpreted as described in [RFC2119].
91
92 This specification expresses normative syntax rules using Augmented
93 Backus-Naur Form (ABNF) [RFC5234] notation.
94
953. Syntax
96
97 A JSON Pointer is a Unicode string (see [RFC4627], Section 3)
98 containing a sequence of zero or more reference tokens, each prefixed
99 by a '/' (%x2F) character.
100
101 Because the characters '~' (%x7E) and '/' (%x2F) have special
102 meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/'
103 needs to be encoded as '~1' when these characters appear in a
104 reference token.
105
106
107
108
109
110
111
112
113
114Bryan, et al. Standards Track [Page 2]
115
116RFC 6901 JSON Pointer April 2013
117
118
119 The ABNF syntax of a JSON Pointer is:
120
121 json-pointer = *( "/" reference-token )
122 reference-token = *( unescaped / escaped )
123 unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
124 ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
125 escaped = "~" ( "0" / "1" )
126 ; representing '~' and '/', respectively
127
128 It is an error condition if a JSON Pointer value does not conform to
129 this syntax (see Section 7).
130
131 Note that JSON Pointers are specified in characters, not as bytes.
132
1334. Evaluation
134
135 Evaluation of a JSON Pointer begins with a reference to the root
136 value of a JSON document and completes with a reference to some value
137 within the document. Each reference token in the JSON Pointer is
138 evaluated sequentially.
139
140 Evaluation of each reference token begins by decoding any escaped
141 character sequence. This is performed by first transforming any
142 occurrence of the sequence '~1' to '/', and then transforming any
143 occurrence of the sequence '~0' to '~'. By performing the
144 substitutions in this order, an implementation avoids the error of
145 turning '~01' first into '~1' and then into '/', which would be
146 incorrect (the string '~01' correctly becomes '~1' after
147 transformation).
148
149 The reference token then modifies which value is referenced according
150 to the following scheme:
151
152 o If the currently referenced value is a JSON object, the new
153 referenced value is the object member with the name identified by
154 the reference token. The member name is equal to the token if it
155 has the same number of Unicode characters as the token and their
156 code points are byte-by-byte equal. No Unicode character
157 normalization is performed. If a referenced member name is not
158 unique in an object, the member that is referenced is undefined,
159 and evaluation fails (see below).
160
161
162
163
164
165
166
167
168
169
170Bryan, et al. Standards Track [Page 3]
171
172RFC 6901 JSON Pointer April 2013
173
174
175 o If the currently referenced value is a JSON array, the reference
176 token MUST contain either:
177
178 * characters comprised of digits (see ABNF below; note that
179 leading zeros are not allowed) that represent an unsigned
180 base-10 integer value, making the new referenced value the
181 array element with the zero-based index identified by the
182 token, or
183
184 * exactly the single character "-", making the new referenced
185 value the (nonexistent) member after the last array element.
186
187 The ABNF syntax for array indices is:
188
189 array-index = %x30 / ( %x31-39 *(%x30-39) )
190 ; "0", or digits without a leading "0"
191
192 Implementations will evaluate each reference token against the
193 document's contents and will raise an error condition if it fails to
194 resolve a concrete value for any of the JSON pointer's reference
195 tokens. For example, if an array is referenced with a non-numeric
196 token, an error condition will be raised. See Section 7 for details.
197
198 Note that the use of the "-" character to index an array will always
199 result in such an error condition because by definition it refers to
200 a nonexistent array element. Thus, applications of JSON Pointer need
201 to specify how that character is to be handled, if it is to be
202 useful.
203
204 Any error condition for which a specific action is not defined by the
205 JSON Pointer application results in termination of evaluation.
206
2075. JSON String Representation
208
209 A JSON Pointer can be represented in a JSON string value. Per
210 [RFC4627], Section 2.5, all instances of quotation mark '"' (%x22),
211 reverse solidus '\' (%x5C), and control (%x00-1F) characters MUST be
212 escaped.
213
214 Note that before processing a JSON string as a JSON Pointer,
215 backslash escape sequences must be unescaped.
216
217
218
219
220
221
222
223
224
225
226Bryan, et al. Standards Track [Page 4]
227
228RFC 6901 JSON Pointer April 2013
229
230
231 For example, given the JSON document
232
233 {
234 "foo": ["bar", "baz"],
235 "": 0,
236 "a/b": 1,
237 "c%d": 2,
238 "e^f": 3,
239 "g|h": 4,
240 "i\\j": 5,
241 "k\"l": 6,
242 " ": 7,
243 "m~n": 8
244 }
245
246 The following JSON strings evaluate to the accompanying values:
247
248 "" // the whole document
249 "/foo" ["bar", "baz"]
250 "/foo/0" "bar"
251 "/" 0
252 "/a~1b" 1
253 "/c%d" 2
254 "/e^f" 3
255 "/g|h" 4
256 "/i\\j" 5
257 "/k\"l" 6
258 "/ " 7
259 "/m~0n" 8
260
2616. URI Fragment Identifier Representation
262
263 A JSON Pointer can be represented in a URI fragment identifier by
264 encoding it into octets using UTF-8 [RFC3629], while percent-encoding
265 those characters not allowed by the fragment rule in [RFC3986].
266
267 Note that a given media type needs to specify JSON Pointer as its
268 fragment identifier syntax explicitly (usually, in its registration
269 [RFC6838]). That is, just because a document is JSON does not imply
270 that JSON Pointer can be used as its fragment identifier syntax. In
271 particular, the fragment identifier syntax for application/json is
272 not JSON Pointer.
273
274
275
276
277
278
279
280
281
282Bryan, et al. Standards Track [Page 5]
283
284RFC 6901 JSON Pointer April 2013
285
286
287 Given the same example document as above, the following URI fragment
288 identifiers evaluate to the accompanying values:
289
290 # // the whole document
291 #/foo ["bar", "baz"]
292 #/foo/0 "bar"
293 #/ 0
294 #/a~1b 1
295 #/c%25d 2
296 #/e%5Ef 3
297 #/g%7Ch 4
298 #/i%5Cj 5
299 #/k%22l 6
300 #/%20 7
301 #/m~0n 8
302
3037. Error Handling
304
305 In the event of an error condition, evaluation of the JSON Pointer
306 fails to complete.
307
308 Error conditions include, but are not limited to:
309
310 o Invalid pointer syntax
311
312 o A pointer that references a nonexistent value
313
314 This specification does not define how errors are handled. An
315 application of JSON Pointer SHOULD specify the impact and handling of
316 each type of error.
317
318 For example, some applications might stop pointer processing upon an
319 error, while others may attempt to recover from missing values by
320 inserting default ones.
321
3228. Security Considerations
323
324 A given JSON Pointer is not guaranteed to reference an actual JSON
325 value. Therefore, applications using JSON Pointer should anticipate
326 this situation by defining how a pointer that does not resolve ought
327 to be handled.
328
329 Note that JSON pointers can contain the NUL (Unicode U+0000)
330 character. Care is needed not to misinterpret this character in
331 programming languages that use NUL to mark the end of a string.
332
333
334
335
336
337
338Bryan, et al. Standards Track [Page 6]
339
340RFC 6901 JSON Pointer April 2013
341
342
3439. Acknowledgements
344
345 The following individuals contributed ideas, feedback, and wording to
346 this specification:
347
348 Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin J.
349 Duerst, Bjoern Hoehrmann, James H. Manger, Drew Perttula, and
350 Julian Reschke.
351
35210. References
353
35410.1. Normative References
355
356 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
357 Requirement Levels", BCP 14, RFC 2119, March 1997.
358
359 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
360 10646", STD 63, RFC 3629, November 2003.
361
362 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
363 Resource Identifier (URI): Generic Syntax", STD 66,
364 RFC 3986, January 2005.
365
366 [RFC4627] Crockford, D., "The application/json Media Type for
367 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
368
369 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
370 Specifications: ABNF", STD 68, RFC 5234, January 2008.
371
37210.2. Informative References
373
374 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
375 Specifications and Registration Procedures", BCP 13,
376 RFC 6838, January 2013.
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394Bryan, et al. Standards Track [Page 7]
395
396RFC 6901 JSON Pointer April 2013
397
398
399Authors' Addresses
400
401 Paul C. Bryan (editor)
402 Salesforce.com
403
404 Phone: +1 604 783 1481
405 EMail: pbryan@anode.ca
406
407
408 Kris Zyp
409 SitePen (USA)
410
411 Phone: +1 650 968 8787
412 EMail: kris@sitepen.com
413
414
415 Mark Nottingham (editor)
416 Akamai
417
418 EMail: mnot@mnot.net
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450Bryan, et al. Standards Track [Page 8]
451