idnits 2.17.1 draft-hallambaker-jsonbcd-22.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 Authors' Addresses Section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (20 April 2022) is 736 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC2119' is mentioned on line 175, but not defined ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. M. Hallam-Baker 3 Internet-Draft 20 April 2022 4 Intended status: Informational 5 Expires: 22 October 2022 7 Binary Encodings for JavaScript Object Notation: JSON-B, JSON-C, JSON-D 8 draft-hallambaker-jsonbcd-22 10 Abstract 12 Three binary encodings for JavaScript Object Notation (JSON) are 13 presented. JSON-B (Binary) is a strict superset of the JSON encoding 14 that permits efficient binary encoding of intrinsic JavaScript data 15 types. JSON-C (Compact) is a strict superset of JSON-B that supports 16 compact representation of repeated data strings with short numeric 17 codes. JSON-D (Data) supports additional binary data types for 18 integer and floating-point representations for use in scientific 19 applications where conversion between binary and decimal 20 representations would cause a loss of precision. 22 This document is also available online at 23 http://mathmesh.com/Documents/draft-hallambaker-jsonbcd.html. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 22 October 2022. 42 Copyright Notice 44 Copyright (c) 2022 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 59 2.2. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 4 60 2.3. Related Specifications . . . . . . . . . . . . . . . . . 5 61 2.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 62 3. Extended JSON Grammar . . . . . . . . . . . . . . . . . . . . 5 63 4. JSON-B . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 4.1. JSON-B Examples . . . . . . . . . . . . . . . . . . . . . 9 65 5. JSON-C . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 5.1. JSON-C Examples . . . . . . . . . . . . . . . . . . . . . 11 67 6. JSON-D (Data) . . . . . . . . . . . . . . . . . . . . . . . . 12 68 7. JBCD Frames and Records . . . . . . . . . . . . . . . . . . . 13 69 8. JSON-BCD Application Binding . . . . . . . . . . . . . . . . 15 70 8.1. JSON Binding . . . . . . . . . . . . . . . . . . . . . . 15 71 8.2. JSON-B Binding . . . . . . . . . . . . . . . . . . . . . 16 72 8.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 17 73 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 74 10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 75 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 76 12. Normative References . . . . . . . . . . . . . . . . . . . . 18 77 13. Informative References . . . . . . . . . . . . . . . . . . . 19 79 1. Introduction 81 JavaScript Object Notation (JSON) is a simple text encoding for the 82 JavaScript Data model that has found wide application beyond its 83 original field of use. In particular JSON has rapidly become a 84 preferred encoding for Web Services. 86 JSON encoding supports just four fundamental data types (integer, 87 floating point, string and boolean), arrays and objects which consist 88 of a list of tag-value pairs. 90 Although the JSON encoding is sufficient for many purposes it is not 91 always efficient. In particular there is no efficient representation 92 for blocks of binary data. Use of base64 encoding increases data 93 volume by 33%. This overhead increases exponentially in applications 94 where nested binary encodings are required making use of JSON 95 encoding unsatisfactory in cryptographic applications where nested 96 binary structures are frequently required. 98 Another source of inefficiency in JSON encoding is the repeated 99 occurrence of object tags. A JSON encoding containing an array of a 100 hundred objects such as {"first":1,"second":2} will contain a hundred 101 occurrences of the string "first" (seven bytes) and a hundred 102 occurrences of the string "second" (eight bytes). Using two byte 103 code sequences in place of strings allows a saving of 11 bytes per 104 object without loss of information, a saving of 50%. 106 A third objection to the use of JSON encoding is that floating point 107 numbers can only be represented in decimal form and this necessarily 108 involves a loss of precision when converting between binary and 109 decimal representations. While such issues are rarely important in 110 network applications they can be critical in scientific applications. 111 It is not acceptable for saving and restoring a data set to change 112 the result of a calculation. 114 1.1. Objectives 116 The following were identified as core objectives for a binary JSON 117 encoding: 119 * Easy to convert existing encoders and decoders to add binary 120 support 122 * Efficient encoding of binary data 124 * Ability to convert from JSON to binary encoding in a streaming 125 mode (i.e. without reading the entire binary data block before 126 beginning encoding. 128 * Lossless encoding of JavaScript data types 130 * The ability to support JSON tag compression and extended data 131 types are considered desirable but not essential for typical 132 network applications. 134 Three binary encodings are defined: 136 JSON-B (Binary) Encodes JSON data in binary. Only the JavaScript 137 data model is supported (i.e. atomic types are integers, double or 138 string). Integers may be 8, 16, 32 or 64 bits either signed or 139 unsigned. Floating points are IEEE 754 binary64 format [IEEE754]. 140 Supports chunked encoding for binary and UTF-8 string types. 142 JSON-C (Compact) As JSON-B but with support for representing JSON 143 tags in numeric code form (16 bit code space). This is done for 144 both compact encoding and to allow simplification of encoders/ 145 decoders in constrained environments. Codes may be defined inline 146 or by reference to a known dictionary of codes referenced via a 147 digest value. 149 JSON-D (Data) As JSON-C but with support for representing additional 150 data types without loss of precision. In particular other IEEE 151 754 floating point formats, both binary and decimal and Intel's 80 152 bit floating point, plus 128 bit integers and bignum integers. 154 Each encoding is a proper superset of JSON, JSON-C is a proper 155 superset of JSON-B and JSON-D is a proper superset of JSON-C. Thus a 156 single decoder MAY be used for all three new encodings and for JSON. 157 Figure 1 shows these relationships graphically: 159 (Artwork only available as svg: No external link available, see 160 draft-hallambaker-jsonbcd-22.html for artwork.) 162 Figure 1: Encoding Relationships. 164 2. Definitions 166 This section presents the related specifications and standard, the 167 terms that are used as terms of art within the documents and the 168 terms used as requirements language. 170 2.1. Requirements Language 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 174 document are to be interpreted as described in [RFC2119]. 176 2.2. Defined Terms 178 The terms of art used in this document are described in the _Mesh 179 Architecture Guide_ [draft-hallambaker-mesh-architecture]. 181 2.3. Related Specifications 183 The JSON-B, JSON-C and JSON-D encodings are all based on the JSON 184 grammar [RFC7159]. IEEE 754 Floating Point Standard is used for 185 encoding floating point numbers [IEEE754], 187 2.4. Terminology 189 No new terms of art are defined 191 3. Extended JSON Grammar 193 The JSON-B, JSON-C and JSON-D encodings are all based on the JSON 194 grammar [RFC7159] using the same syntactic structure but different 195 lexical encodings. 197 JSON-B0 and JSON-C0 replace the JSON lexical encodings for strings 198 and numbers with binary encodings. JSON-B1 and JSON-C1 allow either 199 lexical encoding to be used. Thus, any valid JSON encoding is a 200 valid JSON-B1 or JSON-C1 encoding. 202 The grammar of JSON-B, JSON-C and JSON-D is a superset of the JSON 203 grammar. The following productions are added to the grammar: 205 x-value Binary encodings for data values. As the binary value 206 encodings are all self-delimiting 208 x-member An object member where the value is specified as an X-value 209 and thus does not require a value-separator. 211 b-value Binary data encodings defined in JSON-B. 213 b-string Defined length string encoding defined in JSON-B. 215 c-def Tag code definition defined in JSON-C. These may only appear 216 before the beginning of an Object or Array and before any 217 preceding white space. 219 c-tag Tag code value defined in JSON-C. 221 d-value Additional binary data encodings defined in JSON-D for use 222 in scientific data applications. 224 The JSON grammar is modified to permit the use of x-value productions 225 in place of ( value value-separator ) : 227 JSON-text = (object / array) 229 object = *cdef begin-object [ 230 *( member value-separator | x-member ) 231 (member | x-member) ] end-object 233 member = tag value 234 x-member = tag x-value 236 tag = string name-separator | b-string | c-tag 238 array = *cdef begin-array [ *( value value-separator | x-value ) 239 (value | x-value) ] end-array 241 x-value = b-value / d-value 243 value = false / null / true / object / array / number / string 245 name-separator = ws %x3A ws ; : colon 246 value-separator = ws %x2C ws ; , comma 248 The following lexical values are unchanged: 249 begin-array = ws %x5B ws ; [ left square bracket 250 begin-object = ws %x7B ws ; { left curly bracket 251 end-array = ws %x5D ws ; ] right square bracket 252 end-object = ws %x7D ws ; } right curly bracket 254 ws = *( %x20 %x09 %x0A %x0D ) 256 false = %x66.61.6c.73.65 ; false 257 null = %x6e.75.6c.6c ; null 258 true = %x74.72.75.65 ; true 260 The productions number and string are defined as before: 262 number = [ minus ] int [ frac ] [ exp ] 263 decimal-point = %x2E ; . 264 digit1-9 = %x31-39 ; 1-9 265 e = %x65 / %x45 ; e E 266 exp = e [ minus / plus ] 1*DIGIT 267 frac = decimal-point 1*DIGIT 268 int = zero / ( digit1-9 *DIGIT ) 269 minus = %x2D ; - 270 plus = %x2B ; + 271 zero = %x30 ; 0 273 string = quotation-mark *char quotation-mark 274 char = unescaped / 275 escape ( %x22 / %x5C / %x2F / %x62 / %x66 / 276 %x6E / %x72 / %x74 / %x75 4HEXDIG ) 278 escape = %x5C ; \ 279 quotation-mark = %x22 ; " 280 unescaped = %x20-21 / %x23-5B / %x5D-10FFFF 282 4. JSON-B 284 The JSON-B encoding defines the b-value and b-string productions: 286 b-value = b-atom | b-string | b-data | b-integer | 287 b-float 289 b-string = *( string-chunk ) string-term 290 b-data = *( data-chunk ) data-last 292 b-integer = p-int8 | p-int16 | p-int32 | p-int64 | p-bignum16 | 293 n-int8 | n-int16 | n-int32 | n-int64 | n-bignum16 295 b-float = binary64 297 The lexical encodings of the productions are defined in the following 298 tables where the column 'tag' specifies the byte code that begins the 299 production, 'Fixed' specifies the number of data bytes that follow 300 and 'Length' specifies the number of bytes used to define the length 301 of a variable length field following the data bytes: 303 +==============+=====+=======+========+==================+ 304 | Production | Tag | Fixed | Length | Data Description | 305 +==============+=====+=======+========+==================+ 306 | string-term | x80 | - | 1 | Terminal String | 307 | | | | | 8 bit length | 308 +--------------+-----+-------+--------+------------------+ 309 | string-term | x81 | - | 2 | Terminal String | 310 | | | | | 16 bit length | 311 +--------------+-----+-------+--------+------------------+ 312 | string-term | x82 | - | 4 | Terminal String | 313 | | | | | 32 bit length | 314 +--------------+-----+-------+--------+------------------+ 315 | string-term | x83 | - | 8 | Terminal String | 316 | | | | | 64 bit length | 317 +--------------+-----+-------+--------+------------------+ 318 | string-chunk | x84 | - | 1 | Terminal String | 319 | | | | | 8 bit length | 320 +--------------+-----+-------+--------+------------------+ 321 | string-chunk | x85 | - | 2 | Terminal String | 322 | | | | | 16 bit length | 323 +--------------+-----+-------+--------+------------------+ 324 | string-chunk | x86 | - | 4 | Terminal String | 325 | | | | | 32 bit length | 326 +--------------+-----+-------+--------+------------------+ 327 | string-chunk | x87 | - | 8 | Terminal String | 328 | | | | | 64 bit length | 329 +--------------+-----+-------+--------+------------------+ 330 | data-term | x88 | - | 1 | Terminal String | 331 | | | | | 8 bit length | 332 +--------------+-----+-------+--------+------------------+ 333 | data-term | x89 | - | 2 | Terminal String | 334 | | | | | 16 bit length | 335 +--------------+-----+-------+--------+------------------+ 336 | data-term | x8A | - | 4 | Terminal String | 337 | | | | | 32 bit length | 338 +--------------+-----+-------+--------+------------------+ 339 | data-term | x8B | - | 8 | Terminal String | 340 | | | | | 64 bit length | 341 +--------------+-----+-------+--------+------------------+ 342 | data-chunk | X8C | - | 1 | Terminal String | 343 | | | | | 8 bit length | 344 +--------------+-----+-------+--------+------------------+ 345 | data-chunk | x8D | - | 2 | Terminal String | 346 | | | | | 16 bit length | 347 +--------------+-----+-------+--------+------------------+ 348 | data-chunk | x8E | - | 4 | Terminal String | 349 | | | | | 32 bit length | 350 +--------------+-----+-------+--------+------------------+ 351 | data-chunk | x8F | - | 8 | Terminal String | 352 | | | | | 64 bit length | 353 +--------------+-----+-------+--------+------------------+ 355 Table 1 357 Table 1: Codes for String and Data items 358 +============+=====+=======+========+=========================+ 359 | Production | Tag | Fixed | Length | Data Description | 360 +============+=====+=======+========+=========================+ 361 | p-int8 | xA0 | 1 | - | Positive 8 bit Integer | 362 +------------+-----+-------+--------+-------------------------+ 363 | p-int16 | xa1 | 2 | - | Positive 16 bit Integer | 364 +------------+-----+-------+--------+-------------------------+ 365 | p-int32 | xa2 | 4 | - | Positive 32 bit Integer | 366 +------------+-----+-------+--------+-------------------------+ 367 | p-int64 | xa3 | 8 | - | Positive 64 bit Integer | 368 +------------+-----+-------+--------+-------------------------+ 369 | p-bignum16 | Xa7 | - | 2 | Positive Bignum | 370 +------------+-----+-------+--------+-------------------------+ 371 | n-int8 | xA8 | 1 | - | Negative 8 bit Integer | 372 +------------+-----+-------+--------+-------------------------+ 373 | n-int16 | xA9 | 2 | - | Negative 16 bit Integer | 374 +------------+-----+-------+--------+-------------------------+ 375 | n-int32 | xAA | 4 | - | Negative 32 bit Integer | 376 +------------+-----+-------+--------+-------------------------+ 377 | n-int64 | xAB | 8 | - | Negative 64 bit Integer | 378 +------------+-----+-------+--------+-------------------------+ 379 | n-bignum16 | xAF | - | 2 | Negative Bignum | 380 +------------+-----+-------+--------+-------------------------+ 381 | binary64 | x92 | 8 | - | IEEE 754 Floating Point | 382 | | | | | Binary 64 bit | 383 +------------+-----+-------+--------+-------------------------+ 384 | b-value | xB0 | - | - | True | 385 +------------+-----+-------+--------+-------------------------+ 386 | b-value | xB1 | - | - | False | 387 +------------+-----+-------+--------+-------------------------+ 388 | b-value | xB2 | - | - | Null | 389 +------------+-----+-------+--------+-------------------------+ 391 Table 2 393 Table 2: Codes for Integers, 64 Bit Floating Point, Boolean and Null 394 items. 396 A data type commonly used in networking that is not defined in this 397 scheme is a datetime representation. To define such a data type, a 398 string containing a date-time value in Internet type format is 399 typically used. 401 4.1. JSON-B Examples 403 The following examples show examples of using JSON-B encoding: 405 A0 2A 42 (as 8 bit integer) 406 A1 00 2A 42 (as 16 bit integer) 407 A2 00 00 00 2A 42 (as 32 bit integer) 408 A3 00 00 00 00 00 00 00 2A 42 (as 64 bit integer) 409 A5 00 01 42 42 (as Bignum) 411 80 05 48 65 6c 6c 6f "Hello" (single chunk) 412 81 00 05 48 65 6c 6c 6f "Hello" (single chunk) 413 84 05 48 65 6c 6c 6f 80 00 "Hello" (as two chunks) 415 92 3f f0 00 00 00 00 00 00 1.0 416 92 40 24 00 00 00 00 00 00 10.0 417 92 40 09 21 fb 54 44 2e ea 3.14159265359 418 92 bf f0 00 00 00 00 00 00 -1.0 420 B0 true 421 B1 false 422 B2 null 424 5. JSON-C 426 JSON-C (Compressed) permits numeric code values to be substituted for 427 strings and binary data. Tag codes MAY be 8, 16 or 32 bits long 428 encoded in network byte order. 430 Tag codes MUST be defined before they are referenced. A Tag code MAY 431 be defined before the corresponding data or string value is used or 432 at the same time that it is used. 434 A dictionary is a list of tag code definitions. An encoding MAY 435 incorporate definitions from a dictionary using the dict-hash 436 production. The dict hash production specifies a (positive) offset 437 value to be added to the entries in the dictionary followed by the 438 UDF fingerprint [draft-hallambaker-udf] of the dictionary to be used. 440 +============+=====+=======+========+===============================+ 441 | Production | Tag | Fixed | Length | Data Description | 442 +============+=====+=======+========+===============================+ 443 | c-tag | xC0 | 1 | - | 8 bit tag code | 444 +------------+-----+-------+--------+-------------------------------+ 445 | c-tag | xC1 | 2 | - | 16 bit tag code | 446 +------------+-----+-------+--------+-------------------------------+ 447 | c-tag | xC2 | 4 | - | 32 bit tag code | 448 +------------+-----+-------+--------+-------------------------------+ 449 | c-def | xC4 | 1 | - | 8 bit tag definition | 450 +------------+-----+-------+--------+-------------------------------+ 451 | c-def | xC5 | 2 | - | 16 bit tag definition | 452 +------------+-----+-------+--------+-------------------------------+ 453 | c-def | xC6 | 4 | - | 32 bit tag definition | 454 +------------+-----+-------+--------+-------------------------------+ 455 | c-tag | xC8 | 1 | - | 8 bit tag code and | 456 | | | | | definition | 457 +------------+-----+-------+--------+-------------------------------+ 458 | c-tag | xC9 | 2 | - | 16 bit tag code and | 459 | | | | | definition | 460 +------------+-----+-------+--------+-------------------------------+ 461 | c-tag | xCA | 4 | - | 32 bit tag code and | 462 | | | | | definition | 463 +------------+-----+-------+--------+-------------------------------+ 464 | c-def | xCC | 1 | - | 8 bit tag dictionary | 465 | | | | | definition | 466 +------------+-----+-------+--------+-------------------------------+ 467 | c-def | xCD | 2 | - | 16 bit tag dictionary | 468 | | | | | definition | 469 +------------+-----+-------+--------+-------------------------------+ 470 | c-def | xCE | 4 | - | 32 bit tag dictionary | 471 | | | | | definition | 472 +------------+-----+-------+--------+-------------------------------+ 473 | dict-hash | xD0 | 4 | 1 | UDF fingerprint of | 474 | | | | | dictionary | 475 +------------+-----+-------+--------+-------------------------------+ 477 Table 3 479 Table 3: Codes Used for Compression 481 All integer values are encoded in Network Byte Order (most 482 significant byte first). 484 5.1. JSON-C Examples 486 The following examples show examples of using JSON-C encoding: 488 C8 20 80 05 48 65 6c 6c 6f "Hello" 20 = "Hello" 489 C4 21 80 05 48 65 6c 6c 6f 21 = "Hello" 490 C0 20 "Hello" 491 C1 00 20 "Hello" 493 D0 00 00 01 00 20 Insert dictionary at code 256 494 e3 b0 c4 42 98 fc 1c 14 495 9a fb f4 c8 99 6f b9 24 496 27 ae 41 e4 64 9b 93 4c 497 a4 95 99 1b 78 52 b8 55 UDF (C4 21 80 05 48 65 6c 6c 6f) 499 6. JSON-D (Data) 501 JSON-B and JSON-C only support the two numeric types defined in the 502 JavaScript data model: Integers and 64 bit floating point values. 503 JSON-D (Data) defines binary encodings for additional data types that 504 are commonly used in scientific applications. These comprise 505 positive and negative 128 bit integers, six additional floating point 506 representations defined by IEEE 754 [IEEE754] and the Intel extended 507 precision 80 bit floating point representation [INTEL]. 509 Should the need arise, even bigger bignums could be defined with the 510 length specified as a 32 bit value permitting bignums of up to 2^35 511 bits to be represented. 513 d-value = d-integer | d-float 515 d-float = binary16 | binary32 | binary128 | binary80 | 516 decimal32 | decimal64 | decimal 128 518 The codes for these values are as follows: 520 +============+=====+=======+========+==========================+ 521 | Production | Tag | Fixed | Length | Data Description | 522 +============+=====+=======+========+==========================+ 523 | p-int128 | xA4 | 16 | - | Positive 128 bit Integer | 524 +------------+-----+-------+--------+--------------------------+ 525 | n-int128 | xAC | 16 | - | Negative 128 bit Integer | 526 +------------+-----+-------+--------+--------------------------+ 527 | binary16 | x90 | 2 | - | IEEE 754 Floating Point | 528 | | | | | Binary 16 bit | 529 +------------+-----+-------+--------+--------------------------+ 530 | binary32 | x91 | 4 | - | IEEE 754 Floating Point | 531 | | | | | Binary 32 bit | 532 +------------+-----+-------+--------+--------------------------+ 533 | binary128 | x94 | 16 | - | IEEE 754 Floating Point | 534 | | | | | Binary 64 bit | 535 +------------+-----+-------+--------+--------------------------+ 536 | Intel80 | x95 | 10 | - | Intel extended Floating | 537 | | | | | Point 80 bit | 538 +------------+-----+-------+--------+--------------------------+ 539 | decimal32 | x96 | 4 | - | IEEE 754 Floating Point | 540 | | | | | Decimal 32 | 541 +------------+-----+-------+--------+--------------------------+ 542 | Decimal64 | x97 | 8 | - | IEEE 754 Floating Point | 543 | | | | | Decimal 64 | 544 +------------+-----+-------+--------+--------------------------+ 545 | Decimal128 | x98 | 16 | - | IEEE 754 Floating Point | 546 | | | | | Decimal 128 | 547 +------------+-----+-------+--------+--------------------------+ 549 Table 4 551 Table 4: Additional Codes for Scientific Data 553 7. JBCD Frames and Records 555 Tag codes in the range xF0-XFF are reserved for specifying markers 556 for _frames_ and _records_. These tags are not used to encode JSON 557 data, they are only used to encapsulate opaque binary data blobs as a 558 unit. 560 A JBCD record consists of consist of the tag, a length and the data 561 item. The length indication provided by the record format allows 562 efficient traversal of a sequence of records in the forward direction 563 only. 565 A JBCD Frames consists of consist of the tag, a length and the data 566 item followed by the tag-length sequence repeated with the bytes 567 written in the reverse order. The first length indication allows 568 efficient traversal of a sequence of records in the forward direction 569 and the second allows efficient traversal in the reverse direction. 571 (Artwork only available as svg: No external link available, see 572 draft-hallambaker-jsonbcd-22.html for artwork.) 574 Figure 2: JBCD Records and Frames 576 The JBCD-Frame tags currently defined are: 578 +============+=========+=======+========+=======================+ 579 | Production | Tag | Fixed | Length | Data Description | 580 +============+=========+=======+========+=======================+ 581 | uframe | xF0 | - | 1 | Record, 8 bit length | 582 +------------+---------+-------+--------+-----------------------+ 583 | uframe | xF1 | - | 2 | Record, 16 bit length | 584 +------------+---------+-------+--------+-----------------------+ 585 | uframe | xF2 | - | 4 | Record, 32 bit length | 586 +------------+---------+-------+--------+-----------------------+ 587 | uframe | xF3 | - | 8 | Record, 64 bit length | 588 +------------+---------+-------+--------+-----------------------+ 589 | bframe | xF4 | - | 1 | Frame, 8 bit length | 590 +------------+---------+-------+--------+-----------------------+ 591 | bframe | xF5 | - | 2 | Frame, 16 bit length | 592 +------------+---------+-------+--------+-----------------------+ 593 | bframe | xF6 | - | 4 | Frame, 32 bit length | 594 +------------+---------+-------+--------+-----------------------+ 595 | bframe | xF7 | - | 8 | Frame, 64 bit length | 596 +------------+---------+-------+--------+-----------------------+ 597 | | xF8-xFF | - | - | Reserved | 598 +------------+---------+-------+--------+-----------------------+ 600 Table 5 602 The author does not expect additional framing tags to be added but 603 codes F8-FF are reserved in case this is desired. 605 It may prove convenient to represent message digest values as large 606 integers rather than binary strings. While very few platforms or 607 programming languages support mathematical operations on fixed size 608 integers larger than 64, this is not a major concern since message 609 digests are rarely used for any purpose other than comparison for 610 equality. 612 +============+=====+=======+========+==========================+ 613 | Production | Tag | Fixed | Length | Data Description | 614 +============+=====+=======+========+==========================+ 615 | p-int128 | Xa4 | 16 | - | Positive 128 bit Integer | 616 +------------+-----+-------+--------+--------------------------+ 617 | p-int256 | Xa5 | 32 | - | Positive 256 bit Integer | 618 +------------+-----+-------+--------+--------------------------+ 619 | p-int512 | Xa6 | 64 | - | Positive 512 bit Integer | 620 +------------+-----+-------+--------+--------------------------+ 622 Table 6 624 8. JSON-BCD Application Binding 626 The JSON serialization format is intentionally limited in the range 627 of data types it supports. To serialize data not supported by the 628 JSON data model, it is necessary to specify a means of transforming 629 the unsupported data type into a supported one. 631 In particular JSON does not provide a Date-Time object or a means of 632 encoding binary data except as an array of bytes. 634 The JSON-BCD Application Binding specifies a data model designed to 635 support the needs of specifying network protocols and associated 636 static data. The data model is close to that of JSON with three 637 additional types: 639 * Binary data 641 * DateTime 643 * Object of specified type 645 8.1. JSON Binding 647 The following data field types are specified: 649 Integer 651 Integer values are encoded as JSON number values. 653 Float 655 Float values are encoded as JSON number values. 657 String 658 Test strings are encoded as JSON text strings. 660 Boolean 662 Boolean values are encoded as JSON 'false', 'true' or 'null' tokens 663 according to value. 665 Sequence 667 Sequences of data items that are encoded as JSON arrays 669 Object of known type 671 Objects whose type is known to the receiver are encoded as JSON 672 objects 674 Object of variable type 676 Objects whose type is not known to the receiver are encoded as JSON 677 objects containing a single field whose name describes the type of 678 the object value and whose value contains the value. 680 Binary Data 682 Byte sequences are converted to BASE64-url encoding [RFC4648] and 683 encoded as JSON string values. 685 Date Time 687 Date Time values are converted to Internet time format as described 688 in [RFC3339] and encoded as JSON string values. 690 8.2. JSON-B Binding 692 The JSON-B value allows a superset of the JSON encodings to be used. 694 Integer 696 Integer values are encoded as JSON number values or as JSON-B 697 b-integer values. 699 Float 701 Float values are encoded as JSON number values or as JSON-B b-integer 702 or b-float values. 704 String 705 Test strings are encoded as JSON text strings or as JSON-B b-string 706 values. 708 Boolean 710 Boolean values are encoded as JSON 'false', 'true' or 'null' tokens 711 or as JSON-B b-atom values according to value 713 Sequence 715 Sequences of data items that are encoded as JSON arrays 717 Object of known type 719 Objects whose type is known to the receiver are encoded as JSON 720 objects 722 Object of variable type 724 Objects whose type is not known to the receiver are encoded as JSON 725 objects containing a single field whose name describes the type of 726 the object value and whose value contains the value. 728 Binary Data 730 Byte sequences are converted to BASE64-url encoding [RFC4648] and 731 encoded as JSON string values or as JSON-B b-data values. 733 Date Time 735 Date Time values are converted to Internet time format as described 736 in [RFC3339] and encoded as JSON string values or as JSON-B b-string 737 values. 739 8.3. Examples 741 9. Acknowledgements 743 This work was assisted by conversations with Nico Williams and other 744 participants on the applications area mailing list. 746 10. Security Considerations 748 A correctly implemented data encoding mechanism should not introduce 749 new security vulnerabilities. However, experience demonstrates that 750 some data encoding approaches are more prone to introduce 751 vulnerabilities when incorrectly implemented than others. 753 In particular, whenever variable length data formats are used, the 754 possibility of a buffer overrun vulnerability is introduced. While 755 best practice suggests that a coding language with native mechanisms 756 for bounds checking is the best protection against such errors, such 757 approaches are not always followed. While such vulnerabilities are 758 most commonly seen in the design of decoders, it is possible for the 759 same vulnerabilities to be exploited in encoders. 761 A common source of such errors is the case where nested length 762 encodings are used. For example, a decoder relies on an outermost 763 length encoding that specifies a length on 50 bytes to allocate 764 memory for the entire result and then attempts to copy a string with 765 a declared length of 1000 bytes within the sequence. 767 The extensions to the JSON encoding described in this document are 768 designed to avoid such errors. Length encodings are only used to 769 define the length of x-value constructions which are always terminal 770 and cannot have nested data entries. 772 11. IANA Considerations 774 [TBS list out all the code points that require an IANA registration] 776 12. Normative References 778 [draft-hallambaker-udf] 779 Hallam-Baker, P., "Uniform Data Fingerprint (UDF)", Work 780 in Progress, Internet-Draft, draft-hallambaker-udf-12, 6 781 January 2019, . 784 [IEEE754] IEEE Computer Society, "IEEE Standard for Floating-Point 785 Arithmetic", IEEE 754-2008, 786 DOI 10.1109/IEEESTD.2008.4610935, 29 August 2008, 787 . 789 [INTEL] Intel Corp., "Unknown". 791 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 792 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 793 . 795 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 796 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 797 . 799 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 800 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 801 2014, . 803 13. Informative References 805 [draft-hallambaker-mesh-architecture] 806 Hallam-Baker, P., "Mathematical Mesh 3.0 Part I: 807 Architecture Guide", Work in Progress, Internet-Draft, 808 draft-hallambaker-mesh-architecture-19, 25 October 2021, 809 .