draft-ietf-cbor-7049bis-11.txt   draft-ietf-cbor-7049bis-12.txt 
Network Working Group C. Bormann Network Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Obsoletes: 7049 (if approved) P. Hoffman Obsoletes: 7049 (if approved) P. Hoffman
Intended status: Standards Track ICANN Intended status: Standards Track ICANN
Expires: June 20, 2020 December 18, 2019 Expires: 20 June 2020 18 December 2019
Concise Binary Object Representation (CBOR) Concise Binary Object Representation (CBOR)
draft-ietf-cbor-7049bis-11 draft-ietf-cbor-7049bis-12
Abstract Abstract
The Concise Binary Object Representation (CBOR) is a data format The Concise Binary Object Representation (CBOR) is a data format
whose design goals include the possibility of extremely small code whose design goals include the possibility of extremely small code
size, fairly small message size, and extensibility without the need size, fairly small message size, and extensibility without the need
for version negotiation. These design goals make it different from for version negotiation. These design goals make it different from
earlier binary serializations such as ASN.1 and MessagePack. earlier binary serializations such as ASN.1 and MessagePack.
This document is a revised edition of RFC 7049, with editorial This document is a revised edition of RFC 7049, with editorial
skipping to change at page 2, line 7 skipping to change at page 2, line 7
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 20, 2020. This Internet-Draft will expire on 20 June 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. CBOR Data Models . . . . . . . . . . . . . . . . . . . . . . 7 2. CBOR Data Models . . . . . . . . . . . . . . . . . . . . . . 7
2.1. Extended Generic Data Models . . . . . . . . . . . . . . 8 2.1. Extended Generic Data Models . . . . . . . . . . . . . . 8
2.2. Specific Data Models . . . . . . . . . . . . . . . . . . 9 2.2. Specific Data Models . . . . . . . . . . . . . . . . . . 9
3. Specification of the CBOR Encoding . . . . . . . . . . . . . 9 3. Specification of the CBOR Encoding . . . . . . . . . . . . . 9
3.1. Major Types . . . . . . . . . . . . . . . . . . . . . . . 11 3.1. Major Types . . . . . . . . . . . . . . . . . . . . . . . 11
3.2. Indefinite Lengths for Some Major Types . . . . . . . . . 13 3.2. Indefinite Lengths for Some Major Types . . . . . . . . . 13
3.2.1. The "break" Stop Code . . . . . . . . . . . . . . . . 13 3.2.1. The "break" Stop Code . . . . . . . . . . . . . . . . 13
3.2.2. Indefinite-Length Arrays and Maps . . . . . . . . . . 14 3.2.2. Indefinite-Length Arrays and Maps . . . . . . . . . . 14
3.2.3. Indefinite-Length Byte Strings and Text Strings . . . 16 3.2.3. Indefinite-Length Byte Strings and Text Strings . . . 16
3.3. Floating-Point Numbers and Values with No Content . . . . 16 3.3. Floating-Point Numbers and Values with No Content . . . . 16
3.4. Tagging of Items . . . . . . . . . . . . . . . . . . . . 18 3.4. Tagging of Items . . . . . . . . . . . . . . . . . . . . 18
3.4.1. Standard Date/Time String . . . . . . . . . . . . . . 21 3.4.1. Standard Date/Time String . . . . . . . . . . . . . . 20
3.4.2. Epoch-based Date/Time . . . . . . . . . . . . . . . . 21 3.4.2. Epoch-based Date/Time . . . . . . . . . . . . . . . . 20
3.4.3. Bignums . . . . . . . . . . . . . . . . . . . . . . . 22 3.4.3. Bignums . . . . . . . . . . . . . . . . . . . . . . . 21
3.4.4. Decimal Fractions and Bigfloats . . . . . . . . . . . 22 3.4.4. Decimal Fractions and Bigfloats . . . . . . . . . . . 22
3.4.5. Content Hints . . . . . . . . . . . . . . . . . . . . 24 3.4.5. Content Hints . . . . . . . . . . . . . . . . . . . . 23
3.4.5.1. Encoded CBOR Data Item . . . . . . . . . . . . . 24 3.4.5.1. Encoded CBOR Data Item . . . . . . . . . . . . . 23
3.4.5.2. Expected Later Encoding for CBOR-to-JSON 3.4.5.2. Expected Later Encoding for CBOR-to-JSON
Converters . . . . . . . . . . . . . . . . . . . 24 Converters . . . . . . . . . . . . . . . . . . . . 24
3.4.5.3. Encoded Text . . . . . . . . . . . . . . . . . . 25 3.4.5.3. Encoded Text . . . . . . . . . . . . . . . . . . 24
3.4.6. Self-Described CBOR . . . . . . . . . . . . . . . . . 26 3.4.6. Self-Described CBOR . . . . . . . . . . . . . . . . . 25
4. Serialization Considerations . . . . . . . . . . . . . . . . 26 4. Serialization Considerations . . . . . . . . . . . . . . . . 26
4.1. Preferred Serialization . . . . . . . . . . . . . . . . . 26 4.1. Preferred Serialization . . . . . . . . . . . . . . . . . 26
4.2. Deterministically Encoded CBOR . . . . . . . . . . . . . 27 4.2. Deterministically Encoded CBOR . . . . . . . . . . . . . 27
4.2.1. Core Deterministic Encoding Requirements . . . . . . 28 4.2.1. Core Deterministic Encoding Requirements . . . . . . 27
4.2.2. Additional Deterministic Encoding Considerations . . 29 4.2.2. Additional Deterministic Encoding Considerations . . 28
4.2.3. Length-first map key ordering . . . . . . . . . . . . 30 4.2.3. Length-first map key ordering . . . . . . . . . . . . 30
5. Creating CBOR-Based Protocols . . . . . . . . . . . . . . . . 31 5. Creating CBOR-Based Protocols . . . . . . . . . . . . . . . . 31
5.1. CBOR in Streaming Applications . . . . . . . . . . . . . 32 5.1. CBOR in Streaming Applications . . . . . . . . . . . . . 31
5.2. Generic Encoders and Decoders . . . . . . . . . . . . . . 32 5.2. Generic Encoders and Decoders . . . . . . . . . . . . . . 32
5.3. Validity of Items . . . . . . . . . . . . . . . . . . . . 33 5.3. Validity of Items . . . . . . . . . . . . . . . . . . . . 32
5.3.1. Basic validity . . . . . . . . . . . . . . . . . . . 33 5.3.1. Basic validity . . . . . . . . . . . . . . . . . . . 33
5.3.2. Tag validity . . . . . . . . . . . . . . . . . . . . 34 5.3.2. Tag validity . . . . . . . . . . . . . . . . . . . . 33
5.4. Validity and Evolution . . . . . . . . . . . . . . . . . 34 5.4. Validity and Evolution . . . . . . . . . . . . . . . . . 34
5.5. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.5. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.6. Specifying Keys for Maps . . . . . . . . . . . . . . . . 36 5.6. Specifying Keys for Maps . . . . . . . . . . . . . . . . 35
5.6.1. Equivalence of Keys . . . . . . . . . . . . . . . . . 37 5.6.1. Equivalence of Keys . . . . . . . . . . . . . . . . . 36
5.7. Undefined Values . . . . . . . . . . . . . . . . . . . . 38 5.7. Undefined Values . . . . . . . . . . . . . . . . . . . . 37
6. Converting Data between CBOR and JSON . . . . . . . . . . . . 38 6. Converting Data between CBOR and JSON . . . . . . . . . . . . 38
6.1. Converting from CBOR to JSON . . . . . . . . . . . . . . 38 6.1. Converting from CBOR to JSON . . . . . . . . . . . . . . 38
6.2. Converting from JSON to CBOR . . . . . . . . . . . . . . 39 6.2. Converting from JSON to CBOR . . . . . . . . . . . . . . 39
7. Future Evolution of CBOR . . . . . . . . . . . . . . . . . . 41 7. Future Evolution of CBOR . . . . . . . . . . . . . . . . . . 40
7.1. Extension Points . . . . . . . . . . . . . . . . . . . . 41 7.1. Extension Points . . . . . . . . . . . . . . . . . . . . 41
7.2. Curating the Additional Information Space . . . . . . . . 42 7.2. Curating the Additional Information Space . . . . . . . . 41
8. Diagnostic Notation . . . . . . . . . . . . . . . . . . . . . 42 8. Diagnostic Notation . . . . . . . . . . . . . . . . . . . . . 42
8.1. Encoding Indicators . . . . . . . . . . . . . . . . . . . 43 8.1. Encoding Indicators . . . . . . . . . . . . . . . . . . . 43
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
9.1. Simple Values Registry . . . . . . . . . . . . . . . . . 44 9.1. Simple Values Registry . . . . . . . . . . . . . . . . . 44
9.2. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 44 9.2. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 44
9.3. Media Type ("MIME Type") . . . . . . . . . . . . . . . . 45 9.3. Media Type ("MIME Type") . . . . . . . . . . . . . . . . 45
9.4. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 46 9.4. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 45
9.5. The +cbor Structured Syntax Suffix Registration . . . . . 46 9.5. The +cbor Structured Syntax Suffix Registration . . . . . 46
10. Security Considerations . . . . . . . . . . . . . . . . . . . 47 10. Security Considerations . . . . . . . . . . . . . . . . . . . 47
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
11.1. Normative References . . . . . . . . . . . . . . . . . . 49 11.1. Normative References . . . . . . . . . . . . . . . . . . 48
11.2. Informative References . . . . . . . . . . . . . . . . . 50 11.2. Informative References . . . . . . . . . . . . . . . . . 50
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 53 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 51
Appendix B. Jump Table . . . . . . . . . . . . . . . . . . . . . 57 Appendix B. Jump Table . . . . . . . . . . . . . . . . . . . . . 55
Appendix C. Pseudocode . . . . . . . . . . . . . . . . . . . . . 60 Appendix C. Pseudocode . . . . . . . . . . . . . . . . . . . . . 58
Appendix D. Half-Precision . . . . . . . . . . . . . . . . . . . 62 Appendix D. Half-Precision . . . . . . . . . . . . . . . . . . . 61
Appendix E. Comparison of Other Binary Formats to CBOR's Design Appendix E. Comparison of Other Binary Formats to CBOR's Design
Objectives . . . . . . . . . . . . . . . . . . . . . 63 Objectives . . . . . . . . . . . . . . . . . . . . . . . 62
E.1. ASN.1 DER, BER, and PER . . . . . . . . . . . . . . . . . 64 E.1. ASN.1 DER, BER, and PER . . . . . . . . . . . . . . . . . 63
E.2. MessagePack . . . . . . . . . . . . . . . . . . . . . . . 64 E.2. MessagePack . . . . . . . . . . . . . . . . . . . . . . . 63
E.3. BSON . . . . . . . . . . . . . . . . . . . . . . . . . . 65 E.3. BSON . . . . . . . . . . . . . . . . . . . . . . . . . . 64
E.4. MSDTP: RFC 713 . . . . . . . . . . . . . . . . . . . . . 65 E.4. MSDTP: RFC 713 . . . . . . . . . . . . . . . . . . . . . 64
E.5. Conciseness on the Wire . . . . . . . . . . . . . . . . . 65 E.5. Conciseness on the Wire . . . . . . . . . . . . . . . . . 64
Appendix F. Changes from RFC 7049 . . . . . . . . . . . . . . . 66 Appendix F. Changes from RFC 7049 . . . . . . . . . . . . . . . 65
Appendix G. Well-formedness errors and examples . . . . . . . . 66 Appendix G. Well-formedness errors and examples . . . . . . . . 65
G.1. Examples for CBOR data items that are not well-formed . . 67 G.1. Examples for CBOR data items that are not well-formed . . 66
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 69 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 68
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69
1. Introduction 1. Introduction
There are hundreds of standardized formats for binary representation There are hundreds of standardized formats for binary representation
of structured data (also known as binary serialization formats). Of of structured data (also known as binary serialization formats). Of
those, some are for specific domains of information, while others are those, some are for specific domains of information, while others are
generalized for arbitrary data. In the IETF, probably the best-known generalized for arbitrary data. In the IETF, probably the best-known
formats in the latter category are ASN.1's BER and DER [ASN.1]. formats in the latter category are ASN.1's BER and DER [ASN.1].
The format defined here follows some specific design goals that are The format defined here follows some specific design goals that are
skipping to change at page 4, line 41 skipping to change at page 4, line 40
of the format. of the format.
1.1. Objectives 1.1. Objectives
The objectives of CBOR, roughly in decreasing order of importance, The objectives of CBOR, roughly in decreasing order of importance,
are: are:
1. The representation must be able to unambiguously encode most 1. The representation must be able to unambiguously encode most
common data formats used in Internet standards. common data formats used in Internet standards.
- It must represent a reasonable set of basic data types and * It must represent a reasonable set of basic data types and
structures using binary encoding. "Reasonable" here is structures using binary encoding. "Reasonable" here is
largely influenced by the capabilities of JSON, with the major largely influenced by the capabilities of JSON, with the major
addition of binary byte strings. The structures supported are addition of binary byte strings. The structures supported are
limited to arrays and trees; loops and lattice-style graphs limited to arrays and trees; loops and lattice-style graphs
are not supported. are not supported.
- There is no requirement that all data formats be uniquely * There is no requirement that all data formats be uniquely
encoded; that is, it is acceptable that the number "7" might encoded; that is, it is acceptable that the number "7" might
be encoded in multiple different ways. be encoded in multiple different ways.
2. The code for an encoder or decoder must be able to be compact in 2. The code for an encoder or decoder must be able to be compact in
order to support systems with very limited memory, processor order to support systems with very limited memory, processor
power, and instruction sets. power, and instruction sets.
- An encoder and a decoder need to be implementable in a very * An encoder and a decoder need to be implementable in a very
small amount of code (for example, in class 1 constrained small amount of code (for example, in class 1 constrained
nodes as defined in [RFC7228]). nodes as defined in [RFC7228]).
- The format should use contemporary machine representations of * The format should use contemporary machine representations of
data (for example, not requiring binary-to-decimal data (for example, not requiring binary-to-decimal
conversion). conversion).
3. Data must be able to be decoded without a schema description. 3. Data must be able to be decoded without a schema description.
- Similar to JSON, encoded data should be self-describing so * Similar to JSON, encoded data should be self-describing so
that a generic decoder can be written. that a generic decoder can be written.
4. The serialization must be reasonably compact, but data 4. The serialization must be reasonably compact, but data
compactness is secondary to code compactness for the encoder and compactness is secondary to code compactness for the encoder and
decoder. decoder.
- "Reasonable" here is bounded by JSON as an upper bound in * "Reasonable" here is bounded by JSON as an upper bound in
size, and by implementation complexity maintaining a lower size, and by implementation complexity maintaining a lower
bound. Using either general compression schemes or extensive bound. Using either general compression schemes or extensive
bit-fiddling violates the complexity goals. bit-fiddling violates the complexity goals.
5. The format must be applicable to both constrained nodes and high- 5. The format must be applicable to both constrained nodes and high-
volume applications. volume applications.
- This means it must be reasonably frugal in CPU usage for both * This means it must be reasonably frugal in CPU usage for both
encoding and decoding. This is relevant both for constrained encoding and decoding. This is relevant both for constrained
nodes and for potential usage in applications with a very high nodes and for potential usage in applications with a very high
volume of data. volume of data.
6. The format must support all JSON data types for conversion to and 6. The format must support all JSON data types for conversion to and
from JSON. from JSON.
- It must support a reasonable level of conversion as long as * It must support a reasonable level of conversion as long as
the data represented is within the capabilities of JSON. It the data represented is within the capabilities of JSON. It
must be possible to define a unidirectional mapping towards must be possible to define a unidirectional mapping towards
JSON for all types of data. JSON for all types of data.
7. The format must be extensible, and the extended data must be 7. The format must be extensible, and the extended data must be
decodable by earlier decoders. decodable by earlier decoders.
- The format is designed for decades of use. * The format is designed for decades of use.
- The format must support a form of extensibility that allows * The format must support a form of extensibility that allows
fallback so that a decoder that does not understand an fallback so that a decoder that does not understand an
extension can still decode the message. extension can still decode the message.
- The format must be able to be extended in the future by later * The format must be able to be extended in the future by later
IETF standards. IETF standards.
1.2. Terminology 1.2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
skipping to change at page 13, line 7 skipping to change at page 13, line 7
In major types 6 and 7, many of the possible values are reserved for In major types 6 and 7, many of the possible values are reserved for
future specification. See Section 9 for more information on these future specification. See Section 9 for more information on these
values. values.
Table 1 summarizes the major types defined by CBOR, ignoring the next Table 1 summarizes the major types defined by CBOR, ignoring the next
section for now. The number N in this table stands for the argument, section for now. The number N in this table stands for the argument,
mt for the major type. mt for the major type.
+----+-----------------------+---------------------------------+ +----+-----------------------+---------------------------------+
| mt | Meaning | Content | | mt | Meaning | Content |
+----+-----------------------+---------------------------------+ +====+=======================+=================================+
| 0 | unsigned integer N | - | | 0 | unsigned integer N | - |
| | | | +----+-----------------------+---------------------------------+
| 1 | negative integer -1-N | - | | 1 | negative integer -1-N | - |
| | | | +----+-----------------------+---------------------------------+
| 2 | byte string | N bytes | | 2 | byte string | N bytes |
| | | | +----+-----------------------+---------------------------------+
| 3 | text string | N bytes (UTF-8 text) | | 3 | text string | N bytes (UTF-8 text) |
| | | | +----+-----------------------+---------------------------------+
| 4 | array | N data items (elements) | | 4 | array | N data items (elements) |
| | | | +----+-----------------------+---------------------------------+
| 5 | map | 2N data items (key/value pairs) | | 5 | map | 2N data items (key/value pairs) |
| | | | +----+-----------------------+---------------------------------+
| 6 | tag of number N | 1 data item | | 6 | tag of number N | 1 data item |
| | | | +----+-----------------------+---------------------------------+
| 7 | simple/float | - | | 7 | simple/float | - |
+----+-----------------------+---------------------------------+ +----+-----------------------+---------------------------------+
Table 1: Overview over CBOR major types (definite length encoded) Table 1: Overview over CBOR major types (definite length
encoded)
3.2. Indefinite Lengths for Some Major Types 3.2. Indefinite Lengths for Some Major Types
Four CBOR items (arrays, maps, byte strings, and text strings) can be Four CBOR items (arrays, maps, byte strings, and text strings) can be
encoded with an indefinite length using additional information value encoded with an indefinite length using additional information value
31. This is useful if the encoding of the item needs to begin before 31. This is useful if the encoding of the item needs to begin before
the number of items inside the array or map, or the total length of the number of items inside the array or map, or the total length of
the string, is known. (The application of this is often referred to the string, is known. (The application of this is often referred to
as "streaming" within a data item.) as "streaming" within a data item.)
skipping to change at page 17, line 5 skipping to change at page 17, line 5
3.3. Floating-Point Numbers and Values with No Content 3.3. Floating-Point Numbers and Values with No Content
Major type 7 is for two types of data: floating-point numbers and Major type 7 is for two types of data: floating-point numbers and
"simple values" that do not need any content. Each value of the "simple values" that do not need any content. Each value of the
5-bit additional information in the initial byte has its own separate 5-bit additional information in the initial byte has its own separate
meaning, as defined in Table 2. Like the major types for integers, meaning, as defined in Table 2. Like the major types for integers,
items of this major type do not carry content data; all the items of this major type do not carry content data; all the
information is in the initial bytes. information is in the initial bytes.
+------------+------------------------------------------------------+ +-------------+---------------------------------------------------+
| 5-Bit | Semantics | | 5-Bit Value | Semantics |
| Value | | +=============+===================================================+
+------------+------------------------------------------------------+ | 0..23 | Simple value (value 0..23) |
| 0..23 | Simple value (value 0..23) | +-------------+---------------------------------------------------+
| | | | 24 | Simple value (value 32..255 in following byte) |
| 24 | Simple value (value 32..255 in following byte) | +-------------+---------------------------------------------------+
| | | | 25 | IEEE 754 Half-Precision Float (16 bits follow) |
| 25 | IEEE 754 Half-Precision Float (16 bits follow) | +-------------+---------------------------------------------------+
| | | | 26 | IEEE 754 Single-Precision Float (32 bits follow) |
| 26 | IEEE 754 Single-Precision Float (32 bits follow) | +-------------+---------------------------------------------------+
| | | | 27 | IEEE 754 Double-Precision Float (64 bits follow) |
| 27 | IEEE 754 Double-Precision Float (64 bits follow) | +-------------+---------------------------------------------------+
| | | | 28-30 | Reserved, not well-formed in the present document |
| 28-30 | Reserved, not well-formed in the present document | +-------------+---------------------------------------------------+
| | | | 31 | "break" stop code for indefinite-length items |
| 31 | "break" stop code for indefinite-length items | | | (Section 3.2.1) |
| | (Section 3.2.1) | +-------------+---------------------------------------------------+
+------------+------------------------------------------------------+
Table 2: Values for Additional Information in Major Type 7 Table 2: Values for Additional Information in Major Type 7
As with all other major types, the 5-bit value 24 signifies a single- As with all other major types, the 5-bit value 24 signifies a single-
byte extension: it is followed by an additional byte to represent the byte extension: it is followed by an additional byte to represent the
simple value. (To minimize confusion, only the values 32 to 255 are simple value. (To minimize confusion, only the values 32 to 255 are
used.) This maintains the structure of the initial bytes: as for the used.) This maintains the structure of the initial bytes: as for the
other major types, the length of these always depends on the other major types, the length of these always depends on the
additional information in the first byte. Table 3 lists the values additional information in the first byte. Table 3 lists the values
assigned and available for simple types. assigned and available for simple types.
+---------+-----------------+ +---------+-----------------+
| Value | Semantics | | Value | Semantics |
+---------+-----------------+ +=========+=================+
| 0..19 | (Unassigned) | | 0..19 | (Unassigned) |
| | | +---------+-----------------+
| 20 | False | | 20 | False |
| | | +---------+-----------------+
| 21 | True | | 21 | True |
| | | +---------+-----------------+
| 22 | Null | | 22 | Null |
| | | +---------+-----------------+
| 23 | Undefined value | | 23 | Undefined value |
| | | +---------+-----------------+
| 24..31 | (Reserved) | | 24..31 | (Reserved) |
| | | +---------+-----------------+
| 32..255 | (Unassigned) | | 32..255 | (Unassigned) |
+---------+-----------------+ +---------+-----------------+
Table 3: Simple Values Table 3: Simple Values
An encoder MUST NOT issue two-byte sequences that start with 0xf8 An encoder MUST NOT issue two-byte sequences that start with 0xf8
(major type = 7, additional information = 24) and continue with a (major type = 7, additional information = 24) and continue with a
byte less than 0x20 (32 decimal). Such sequences are not well- byte less than 0x20 (32 decimal). Such sequences are not well-
formed. (This implies that an encoder cannot encode false, true, formed. (This implies that an encoder cannot encode false, true,
null, or undefined in two-byte sequences, only the one-byte variants null, or undefined in two-byte sequences, only the one-byte variants
of these are well-formed.) of these are well-formed.)
The 5-bit values of 25, 26, and 27 are for 16-bit, 32-bit, and 64-bit The 5-bit values of 25, 26, and 27 are for 16-bit, 32-bit, and 64-bit
IEEE 754 binary floating-point values [IEEE754]. These floating- IEEE 754 binary floating-point values [IEEE754]. These floating-
skipping to change at page 19, line 34 skipping to change at page 19, line 14
of the tag (the enclosed data item) is the data item (the value) that of the tag (the enclosed data item) is the data item (the value) that
is being tagged. is being tagged.
IANA maintains a registry of tag numbers as described in Section 9.2. IANA maintains a registry of tag numbers as described in Section 9.2.
Table 4 provides a list of tag numbers that were defined in Table 4 provides a list of tag numbers that were defined in
[RFC7049], with definitions in the rest of this section. Note that [RFC7049], with definitions in the rest of this section. Note that
many other tag numbers have been defined since the publication of many other tag numbers have been defined since the publication of
[RFC7049]; see the registry described at Section 9.2 for the complete [RFC7049]; see the registry described at Section 9.2 for the complete
list. list.
+----------+----------+---------------------------------------------+ +------------+-------------+----------------------------------+
| Tag | Data | Semantics | | Tag Number | Data Item | Semantics |
| Number | Item | | +============+=============+==================================+
+----------+----------+---------------------------------------------+ | 0 | text string | Standard date/time string; see |
| 0 | text | Standard date/time string; see | | | | Section 3.4.1 |
| | string | Section 3.4.1 | +------------+-------------+----------------------------------+
| | | | | 1 | multiple | Epoch-based date/time; see |
| 1 | multiple | Epoch-based date/time; see Section 3.4.2 | | | | Section 3.4.2 |
| | | | +------------+-------------+----------------------------------+
| 2 | byte | Positive bignum; see Section 3.4.3 | | 2 | byte string | Positive bignum; see |
| | string | | | | | Section 3.4.3 |
| | | | +------------+-------------+----------------------------------+
| 3 | byte | Negative bignum; see Section 3.4.3 | | 3 | byte string | Negative bignum; see |
| | string | | | | | Section 3.4.3 |
| | | | +------------+-------------+----------------------------------+
| 4 | array | Decimal fraction; see Section 3.4.4 | | 4 | array | Decimal fraction; see |
| | | | | | | Section 3.4.4 |
| 5 | array | Bigfloat; see Section 3.4.4 | +------------+-------------+----------------------------------+
| | | | | 5 | array | Bigfloat; see Section 3.4.4 |
| 21 | multiple | Expected conversion to base64url encoding; | +------------+-------------+----------------------------------+
| | | see Section 3.4.5.2 | | 21 | multiple | Expected conversion to base64url |
| | | | | | | encoding; see Section 3.4.5.2 |
| 22 | multiple | Expected conversion to base64 encoding; see | +------------+-------------+----------------------------------+
| | | Section 3.4.5.2 | | 22 | multiple | Expected conversion to base64 |
| | | | | | | encoding; see Section 3.4.5.2 |
| 23 | multiple | Expected conversion to base16 encoding; see | +------------+-------------+----------------------------------+
| | | Section 3.4.5.2 | | 23 | multiple | Expected conversion to base16 |
| | | | | | | encoding; see Section 3.4.5.2 |
| 24 | byte | Encoded CBOR data item; see Section 3.4.5.1 | +------------+-------------+----------------------------------+
| | string | | | 24 | byte string | Encoded CBOR data item; see |
| | | | | | | Section 3.4.5.1 |
| 32 | text | URI; see Section 3.4.5.3 | +------------+-------------+----------------------------------+
| | string | | | 32 | text string | URI; see Section 3.4.5.3 |
| | | | +------------+-------------+----------------------------------+
| 33 | text | base64url; see Section 3.4.5.3 | | 33 | text string | base64url; see Section 3.4.5.3 |
| | string | | +------------+-------------+----------------------------------+
| | | | | 34 | text string | base64; see Section 3.4.5.3 |
| 34 | text | base64; see Section 3.4.5.3 | +------------+-------------+----------------------------------+
| | string | | | 35 | text string | Regular expression; see |
| | | | | | | Section 3.4.5.3 |
| 35 | text | Regular expression; see Section 3.4.5.3 | +------------+-------------+----------------------------------+
| | string | | | 36 | text string | MIME message; see |
| | | | | | | Section 3.4.5.3 |
| 36 | text | MIME message; see Section 3.4.5.3 | +------------+-------------+----------------------------------+
| | string | | | 55799 | multiple | Self-described CBOR; see |
| | | | | | | Section 3.4.6 |
| 55799 | multiple | Self-described CBOR; see Section 3.4.6 | +------------+-------------+----------------------------------+
+----------+----------+---------------------------------------------+
Table 4: Tag numbers defined in RFC 7049 Table 4: Tag numbers defined in RFC 7049
Conceptually, tags are interpreted in the generic data model, not at Conceptually, tags are interpreted in the generic data model, not at
(de-)serialization time. A small number of tags (specifically, tag (de-)serialization time. A small number of tags (specifically, tag
number 25 and tag number 29) have been registered with semantics that number 25 and tag number 29) have been registered with semantics that
may require processing at (de-)serialization time: The decoder needs may require processing at (de-)serialization time: The decoder needs
to be aware and the encoder needs to be in control of the exact to be aware and the encoder needs to be in control of the exact
sequence in which data items are encoded into the CBOR data stream. sequence in which data items are encoded into the CBOR data stream.
This means these tags cannot be implemented on top of every generic This means these tags cannot be implemented on top of every generic
CBOR encoder/decoder (which might not reflect the serialization order CBOR encoder/decoder (which might not reflect the serialization order
for entries in a map at the data model level and vice versa); their for entries in a map at the data model level and vice versa); their
skipping to change at page 50, line 32 skipping to change at page 49, line 51
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[TIME_T] The Open Group Base Specifications, "Vol. 1: Base [TIME_T] The Open Group Base Specifications, "Vol. 1: Base
Definitions, Issue 7", Section 4.15 'Seconds Since the Definitions, Issue 7", 2013 Edition, IEEE Std 1003.1,
Epoch', IEEE Std 1003.1, 2013 Edition, 2013, Section 4.15 'Seconds Since the Epoch', 2013,
<http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/
V1_chap04.html#tag_04_15>. V1_chap04.html#tag_04_15>.
11.2. Informative References 11.2. Informative References
[ASN.1] International Telecommunication Union, "Information [ASN.1] International Telecommunication Union, "Information
Technology -- ASN.1 encoding rules: Specification of Basic Technology -- ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, 1994.
[BSON] Various, "BSON - Binary JSON", 2013, [BSON] Various, "BSON - Binary JSON", 2013,
<http://bsonspec.org/>. <http://bsonspec.org/>.
[I-D.ietf-cbor-sequence] [I-D.ietf-cbor-sequence]
Bormann, C., "Concise Binary Object Representation (CBOR) Bormann, C., "Concise Binary Object Representation (CBOR)
Sequences", draft-ietf-cbor-sequence-02 (work in Sequences", Work in Progress, Internet-Draft, draft-ietf-
progress), September 2019. cbor-sequence-02, 25 September 2019, <http://www.ietf.org/
internet-drafts/draft-ietf-cbor-sequence-02.txt>.
[IANA.cbor-simple-values] [IANA.cbor-simple-values]
IANA, "Concise Binary Object Representation (CBOR) Simple IANA, "Concise Binary Object Representation (CBOR) Simple
Values", Values",
<http://www.iana.org/assignments/cbor-simple-values>. <http://www.iana.org/assignments/cbor-simple-values>.
[IANA.cbor-tags] [IANA.cbor-tags]
IANA, "Concise Binary Object Representation (CBOR) Tags", IANA, "Concise Binary Object Representation (CBOR) Tags",
<http://www.iana.org/assignments/cbor-tags>. <http://www.iana.org/assignments/cbor-tags>.
skipping to change at page 52, line 6 skipping to change at page 51, line 25
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
[RFC8618] Dickinson, J., Hague, J., Dickinson, S., Manderson, T., [RFC8618] Dickinson, J., Hague, J., Dickinson, S., Manderson, T.,
and J. Bond, "Compacted-DNS (C-DNS): A Format for DNS and J. Bond, "Compacted-DNS (C-DNS): A Format for DNS
Packet Capture", RFC 8618, DOI 10.17487/RFC8618, September Packet Capture", RFC 8618, DOI 10.17487/RFC8618, September
2019, <https://www.rfc-editor.org/info/rfc8618>. 2019, <https://www.rfc-editor.org/info/rfc8618>.
[SIPHASH] Aumasson, J. and D. Bernstein, "SipHash: A Fast Short- [SIPHASH] Aumasson, J. and D. Bernstein, "SipHash: A Fast Short-
Input PRF", Lecture Notes in Computer Science pp. 489-508, Input PRF", DOI 10.1007/978-3-642-34931-7_28, Lecture
DOI 10.1007/978-3-642-34931-7_28, 2012. Notes in Computer Science pp. 489-508, 2012,
<https://doi.org/10.1007/978-3-642-34931-7_28>.
[YAML] Ben-Kiki, O., Evans, C., and I. Net, "YAML Ain't Markup [YAML] Ben-Kiki, O., Evans, C., and I.d. Net, "YAML Ain't Markup
Language (YAML[TM]) Version 1.2", 3rd Edition, October Language (YAML[TM]) Version 1.2", 3rd Edition, October
2009, <http://www.yaml.org/spec/1.2/spec.html>. 2009, <http://www.yaml.org/spec/1.2/spec.html>.
Appendix A. Examples Appendix A. Examples
The following table provides some CBOR-encoded values in hexadecimal The following table provides some CBOR-encoded values in hexadecimal
(right column), together with diagnostic notation for these values (right column), together with diagnostic notation for these values
(left column). Note that the string "\u00fc" is one form of (left column). Note that the string "\u00fc" is one form of
diagnostic notation for a UTF-8 string containing the single Unicode diagnostic notation for a UTF-8 string containing the single Unicode
character U+00FC, LATIN SMALL LETTER U WITH DIAERESIS (u umlaut). character U+00FC, LATIN SMALL LETTER U WITH DIAERESIS (u umlaut).
skipping to change at page 53, line 26 skipping to change at page 52, line 7
ATTIC FIFTY STATERS). (Note that all these single-character strings ATTIC FIFTY STATERS). (Note that all these single-character strings
could also be represented in native UTF-8 in diagnostic notation, could also be represented in native UTF-8 in diagnostic notation,
just not in an ASCII-only specification like the present one.) In just not in an ASCII-only specification like the present one.) In
the diagnostic notation provided for bignums, their intended numeric the diagnostic notation provided for bignums, their intended numeric
value is shown as a decimal number (such as 18446744073709551616) value is shown as a decimal number (such as 18446744073709551616)
instead of showing a tagged byte string (such as instead of showing a tagged byte string (such as
2(h'010000000000000000')). 2(h'010000000000000000')).
+------------------------------+------------------------------------+ +------------------------------+------------------------------------+
| Diagnostic | Encoded | | Diagnostic | Encoded |
+------------------------------+------------------------------------+ +==============================+====================================+
| 0 | 0x00 | | 0 | 0x00 |
| | | +------------------------------+------------------------------------+
| 1 | 0x01 | | 1 | 0x01 |
| | | +------------------------------+------------------------------------+
| 10 | 0x0a | | 10 | 0x0a |
| | | +------------------------------+------------------------------------+
| 23 | 0x17 | | 23 | 0x17 |
| | | +------------------------------+------------------------------------+
| 24 | 0x1818 | | 24 | 0x1818 |
| | | +------------------------------+------------------------------------+
| 25 | 0x1819 | | 25 | 0x1819 |
| | | +------------------------------+------------------------------------+
| 100 | 0x1864 | | 100 | 0x1864 |
| | | +------------------------------+------------------------------------+
| 1000 | 0x1903e8 | | 1000 | 0x1903e8 |
| | | +------------------------------+------------------------------------+
| 1000000 | 0x1a000f4240 | | 1000000 | 0x1a000f4240 |
| | | +------------------------------+------------------------------------+
| 1000000000000 | 0x1b000000e8d4a51000 | | 1000000000000 | 0x1b000000e8d4a51000 |
| | | +------------------------------+------------------------------------+
| 18446744073709551615 | 0x1bffffffffffffffff | | 18446744073709551615 | 0x1bffffffffffffffff |
| | | +------------------------------+------------------------------------+
| 18446744073709551616 | 0xc249010000000000000000 | | 18446744073709551616 | 0xc249010000000000000000 |
| | | +------------------------------+------------------------------------+
| -18446744073709551616 | 0x3bffffffffffffffff | | -18446744073709551616 | 0x3bffffffffffffffff |
| | | +------------------------------+------------------------------------+
| -18446744073709551617 | 0xc349010000000000000000 | | -18446744073709551617 | 0xc349010000000000000000 |
| | | +------------------------------+------------------------------------+
| -1 | 0x20 | | -1 | 0x20 |
| | | +------------------------------+------------------------------------+
| -10 | 0x29 | | -10 | 0x29 |
| | | +------------------------------+------------------------------------+
| -100 | 0x3863 | | -100 | 0x3863 |
| | | +------------------------------+------------------------------------+
| -1000 | 0x3903e7 | | -1000 | 0x3903e7 |
| | | +------------------------------+------------------------------------+
| 0.0 | 0xf90000 | | 0.0 | 0xf90000 |
| | | +------------------------------+------------------------------------+
| -0.0 | 0xf98000 | | -0.0 | 0xf98000 |
| | | +------------------------------+------------------------------------+
| 1.0 | 0xf93c00 | | 1.0 | 0xf93c00 |
| | | +------------------------------+------------------------------------+
| 1.1 | 0xfb3ff199999999999a | | 1.1 | 0xfb3ff199999999999a |
| | | +------------------------------+------------------------------------+
| 1.5 | 0xf93e00 | | 1.5 | 0xf93e00 |
| | | +------------------------------+------------------------------------+
| 65504.0 | 0xf97bff | | 65504.0 | 0xf97bff |
| | | +------------------------------+------------------------------------+
| 100000.0 | 0xfa47c35000 | | 100000.0 | 0xfa47c35000 |
| | | +------------------------------+------------------------------------+
| 3.4028234663852886e+38 | 0xfa7f7fffff | | 3.4028234663852886e+38 | 0xfa7f7fffff |
| | | +------------------------------+------------------------------------+
| 1.0e+300 | 0xfb7e37e43c8800759c | | 1.0e+300 | 0xfb7e37e43c8800759c |
| | | +------------------------------+------------------------------------+
| 5.960464477539063e-8 | 0xf90001 | | 5.960464477539063e-8 | 0xf90001 |
| | | +------------------------------+------------------------------------+
| 0.00006103515625 | 0xf90400 | | 0.00006103515625 | 0xf90400 |
| | | +------------------------------+------------------------------------+
| -4.0 | 0xf9c400 | | -4.0 | 0xf9c400 |
| | | +------------------------------+------------------------------------+
| -4.1 | 0xfbc010666666666666 | | -4.1 | 0xfbc010666666666666 |
| | | +------------------------------+------------------------------------+
| Infinity | 0xf97c00 | | Infinity | 0xf97c00 |
| | | +------------------------------+------------------------------------+
| NaN | 0xf97e00 | | NaN | 0xf97e00 |
| | | +------------------------------+------------------------------------+
| -Infinity | 0xf9fc00 | | -Infinity | 0xf9fc00 |
| | | +------------------------------+------------------------------------+
| Infinity | 0xfa7f800000 | | Infinity | 0xfa7f800000 |
| | | +------------------------------+------------------------------------+
| NaN | 0xfa7fc00000 | | NaN | 0xfa7fc00000 |
| | | +------------------------------+------------------------------------+
| -Infinity | 0xfaff800000 | | -Infinity | 0xfaff800000 |
| | | +------------------------------+------------------------------------+
| Infinity | 0xfb7ff0000000000000 | | Infinity | 0xfb7ff0000000000000 |
| | | +------------------------------+------------------------------------+
| NaN | 0xfb7ff8000000000000 | | NaN | 0xfb7ff8000000000000 |
| | | +------------------------------+------------------------------------+
| -Infinity | 0xfbfff0000000000000 | | -Infinity | 0xfbfff0000000000000 |
| | | +------------------------------+------------------------------------+
| false | 0xf4 | | false | 0xf4 |
| | | +------------------------------+------------------------------------+
| true | 0xf5 | | true | 0xf5 |
| | | +------------------------------+------------------------------------+
| null | 0xf6 | | null | 0xf6 |
| | | +------------------------------+------------------------------------+
| undefined | 0xf7 | | undefined | 0xf7 |
| | | +------------------------------+------------------------------------+
| simple(16) | 0xf0 | | simple(16) | 0xf0 |
| | | +------------------------------+------------------------------------+
| simple(255) | 0xf8ff | | simple(255) | 0xf8ff |
| | | +------------------------------+------------------------------------+
| 0("2013-03-21T20:04:00Z") | 0xc074323031332d30332d32315432303a | | 0("2013-03-21T20:04:00Z") | 0xc074323031332d30332d32315432303a |
| | 30343a30305a | | | 30343a30305a |
| | | +------------------------------+------------------------------------+
| 1(1363896240) | 0xc11a514b67b0 | | 1(1363896240) | 0xc11a514b67b0 |
| | | +------------------------------+------------------------------------+
| 1(1363896240.5) | 0xc1fb41d452d9ec200000 | | 1(1363896240.5) | 0xc1fb41d452d9ec200000 |
| | | +------------------------------+------------------------------------+
| 23(h'01020304') | 0xd74401020304 | | 23(h'01020304') | 0xd74401020304 |
| | | +------------------------------+------------------------------------+
| 24(h'6449455446') | 0xd818456449455446 | | 24(h'6449455446') | 0xd818456449455446 |
| | | +------------------------------+------------------------------------+
| 32("http://www.example.com") | 0xd82076687474703a2f2f7777772e6578 | | 32("http://www.example.com") | 0xd82076687474703a2f2f7777772e6578 |
| | 616d706c652e636f6d | | | 616d706c652e636f6d |
| | | +------------------------------+------------------------------------+
| h'' | 0x40 | | h'' | 0x40 |
| | | +------------------------------+------------------------------------+
| h'01020304' | 0x4401020304 | | h'01020304' | 0x4401020304 |
| | | +------------------------------+------------------------------------+
| "" | 0x60 | | "" | 0x60 |
| | | +------------------------------+------------------------------------+
| "a" | 0x6161 | | "a" | 0x6161 |
| | | +------------------------------+------------------------------------+
| "IETF" | 0x6449455446 | | "IETF" | 0x6449455446 |
| | | +------------------------------+------------------------------------+
| "\"\\" | 0x62225c | | "\"\\" | 0x62225c |
| | | +------------------------------+------------------------------------+
| "\u00fc" | 0x62c3bc | | "\u00fc" | 0x62c3bc |
| | | +------------------------------+------------------------------------+
| "\u6c34" | 0x63e6b0b4 | | "\u6c34" | 0x63e6b0b4 |
| | | +------------------------------+------------------------------------+
| "\ud800\udd51" | 0x64f0908591 | | "\ud800\udd51" | 0x64f0908591 |
| | | +------------------------------+------------------------------------+
| [] | 0x80 | | [] | 0x80 |
| | | +------------------------------+------------------------------------+
| [1, 2, 3] | 0x83010203 | | [1, 2, 3] | 0x83010203 |
| | | +------------------------------+------------------------------------+
| [1, [2, 3], [4, 5]] | 0x8301820203820405 | | [1, [2, 3], [4, 5]] | 0x8301820203820405 |
| | | +------------------------------+------------------------------------+
| [1, 2, 3, 4, 5, 6, 7, 8, 9, | 0x98190102030405060708090a0b0c0d0e | | [1, 2, 3, 4, 5, 6, 7, 8, 9, | 0x98190102030405060708090a0b0c0d0e |
| 10, 11, 12, 13, 14, 15, 16, | 0f101112131415161718181819 | | 10, 11, 12, 13, 14, 15, 16, | 0f101112131415161718181819 |
| 17, 18, 19, 20, 21, 22, 23, | | | 17, 18, 19, 20, 21, 22, 23, | |
| 24, 25] | | | 24, 25] | |
| | | +------------------------------+------------------------------------+
| {} | 0xa0 | | {} | 0xa0 |
| | | +------------------------------+------------------------------------+
| {1: 2, 3: 4} | 0xa201020304 | | {1: 2, 3: 4} | 0xa201020304 |
| | | +------------------------------+------------------------------------+
| {"a": 1, "b": [2, 3]} | 0xa26161016162820203 | | {"a": 1, "b": [2, 3]} | 0xa26161016162820203 |
| | | +------------------------------+------------------------------------+
| ["a", {"b": "c"}] | 0x826161a161626163 | | ["a", {"b": "c"}] | 0x826161a161626163 |
| | | +------------------------------+------------------------------------+
| {"a": "A", "b": "B", "c": | 0xa5616161416162614261636143616461 | |{"a": "A", "b": "B", "c": "C",| 0xa5616161416162614261636143616461 |
| "C", "d": "D", "e": "E"} | 4461656145 | | "d": "D", "e": "E"} | 4461656145 |
| | | +------------------------------+------------------------------------+
| (_ h'0102', h'030405') | 0x5f42010243030405ff | | (_ h'0102', h'030405') | 0x5f42010243030405ff |
| | | +------------------------------+------------------------------------+
| (_ "strea", "ming") | 0x7f657374726561646d696e67ff | | (_ "strea", "ming") | 0x7f657374726561646d696e67ff |
| | | +------------------------------+------------------------------------+
| [_ ] | 0x9fff | | [_ ] | 0x9fff |
| | | +------------------------------+------------------------------------+
| [_ 1, [2, 3], [_ 4, 5]] | 0x9f018202039f0405ffff | | [_ 1, [2, 3], [_ 4, 5]] | 0x9f018202039f0405ffff |
| | | +------------------------------+------------------------------------+
| [_ 1, [2, 3], [4, 5]] | 0x9f01820203820405ff | | [_ 1, [2, 3], [4, 5]] | 0x9f01820203820405ff |
| | | +------------------------------+------------------------------------+
| [1, [2, 3], [_ 4, 5]] | 0x83018202039f0405ff | | [1, [2, 3], [_ 4, 5]] | 0x83018202039f0405ff |
| | | +------------------------------+------------------------------------+
| [1, [_ 2, 3], [4, 5]] | 0x83019f0203ff820405 | | [1, [_ 2, 3], [4, 5]] | 0x83019f0203ff820405 |
| | | +------------------------------+------------------------------------+
| [_ 1, 2, 3, 4, 5, 6, 7, 8, | 0x9f0102030405060708090a0b0c0d0e0f | |[_ 1, 2, 3, 4, 5, 6, 7, 8, 9, | 0x9f0102030405060708090a0b0c0d0e0f |
| 9, 10, 11, 12, 13, 14, 15, | 101112131415161718181819ff | | 10, 11, 12, 13, 14, 15, 16, | 101112131415161718181819ff |
| 16, 17, 18, 19, 20, 21, 22, | | | 17, 18, 19, 20, 21, 22, 23, | |
| 23, 24, 25] | | | 24, 25] | |
| | | +------------------------------+------------------------------------+
| {_ "a": 1, "b": [_ 2, 3]} | 0xbf61610161629f0203ffff | | {_ "a": 1, "b": [_ 2, 3]} | 0xbf61610161629f0203ffff |
| | | +------------------------------+------------------------------------+
| ["a", {_ "b": "c"}] | 0x826161bf61626163ff | | ["a", {_ "b": "c"}] | 0x826161bf61626163ff |
| | | +------------------------------+------------------------------------+
| {_ "Fun": true, "Amt": -2} | 0xbf6346756ef563416d7421ff | | {_ "Fun": true, "Amt": -2} | 0xbf6346756ef563416d7421ff |
+------------------------------+------------------------------------+ +------------------------------+------------------------------------+
Table 5: Examples of Encoded CBOR Data Items Table 5: Examples of Encoded CBOR Data Items
Appendix B. Jump Table Appendix B. Jump Table
For brevity, this jump table does not show initial bytes that are For brevity, this jump table does not show initial bytes that are
reserved for future extension. It also only shows a selection of the reserved for future extension. It also only shows a selection of the
initial bytes that can be used for optional features. (All unsigned initial bytes that can be used for optional features. (All unsigned
integers are in network byte order.) integers are in network byte order.)
+------------+------------------------------------------------------+ +------------+------------------------------------------------+
| Byte | Structure/Semantics | | Byte | Structure/Semantics |
+------------+------------------------------------------------------+ +============+================================================+
| 0x00..0x17 | Unsigned integer 0x00..0x17 (0..23) | | 0x00..0x17 | Unsigned integer 0x00..0x17 (0..23) |
| | | +------------+------------------------------------------------+
| 0x18 | Unsigned integer (one-byte uint8_t follows) | | 0x18 | Unsigned integer (one-byte uint8_t follows) |
| | | +------------+------------------------------------------------+
| 0x19 | Unsigned integer (two-byte uint16_t follows) | | 0x19 | Unsigned integer (two-byte uint16_t follows) |
| | | +------------+------------------------------------------------+
| 0x1a | Unsigned integer (four-byte uint32_t follows) | | 0x1a | Unsigned integer (four-byte uint32_t follows) |
| | | +------------+------------------------------------------------+
| 0x1b | Unsigned integer (eight-byte uint64_t follows) | | 0x1b | Unsigned integer (eight-byte uint64_t follows) |
| | | +------------+------------------------------------------------+
| 0x20..0x37 | Negative integer -1-0x00..-1-0x17 (-1..-24) | | 0x20..0x37 | Negative integer -1-0x00..-1-0x17 (-1..-24) |
| | | +------------+------------------------------------------------+
| 0x38 | Negative integer -1-n (one-byte uint8_t for n | | 0x38 | Negative integer -1-n (one-byte uint8_t for n |
| | follows) | | | follows) |
| | | +------------+------------------------------------------------+
| 0x39 | Negative integer -1-n (two-byte uint16_t for n | | 0x39 | Negative integer -1-n (two-byte uint16_t for n |
| | follows) | | | follows) |
| | | +------------+------------------------------------------------+
| 0x3a | Negative integer -1-n (four-byte uint32_t for n | | 0x3a | Negative integer -1-n (four-byte uint32_t for |
| | follows) | | | n follows) |
| | | +------------+------------------------------------------------+
| 0x3b | Negative integer -1-n (eight-byte uint64_t for n | | 0x3b | Negative integer -1-n (eight-byte uint64_t for |
| | follows) | | | n follows) |
| | | +------------+------------------------------------------------+
| 0x40..0x57 | byte string (0x00..0x17 bytes follow) | | 0x40..0x57 | byte string (0x00..0x17 bytes follow) |
| | | +------------+------------------------------------------------+
| 0x58 | byte string (one-byte uint8_t for n, and then n | | 0x58 | byte string (one-byte uint8_t for n, and then |
| | bytes follow) | | | n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x59 | byte string (two-byte uint16_t for n, and then n | | 0x59 | byte string (two-byte uint16_t for n, and then |
| | bytes follow) | | | n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x5a | byte string (four-byte uint32_t for n, and then n | | 0x5a | byte string (four-byte uint32_t for n, and |
| | bytes follow) | | | then n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x5b | byte string (eight-byte uint64_t for n, and then n | | 0x5b | byte string (eight-byte uint64_t for n, and |
| | bytes follow) | | | then n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x5f | byte string, byte strings follow, terminated by | | 0x5f | byte string, byte strings follow, terminated |
| | "break" | | | by "break" |
| | | +------------+------------------------------------------------+
| 0x60..0x77 | UTF-8 string (0x00..0x17 bytes follow) | | 0x60..0x77 | UTF-8 string (0x00..0x17 bytes follow) |
| | | +------------+------------------------------------------------+
| 0x78 | UTF-8 string (one-byte uint8_t for n, and then n | | 0x78 | UTF-8 string (one-byte uint8_t for n, and then |
| | bytes follow) | | | n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x79 | UTF-8 string (two-byte uint16_t for n, and then n | | 0x79 | UTF-8 string (two-byte uint16_t for n, and |
| | bytes follow) | | | then n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x7a | UTF-8 string (four-byte uint32_t for n, and then n | | 0x7a | UTF-8 string (four-byte uint32_t for n, and |
| | bytes follow) | | | then n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x7b | UTF-8 string (eight-byte uint64_t for n, and then n | | 0x7b | UTF-8 string (eight-byte uint64_t for n, and |
| | bytes follow) | | | then n bytes follow) |
| | | +------------+------------------------------------------------+
| 0x7f | UTF-8 string, UTF-8 strings follow, terminated by | | 0x7f | UTF-8 string, UTF-8 strings follow, terminated |
| | "break" | | | by "break" |
| | | +------------+------------------------------------------------+
| 0x80..0x97 | array (0x00..0x17 data items follow) | | 0x80..0x97 | array (0x00..0x17 data items follow) |
| | | +------------+------------------------------------------------+
| 0x98 | array (one-byte uint8_t for n, and then n data items | | 0x98 | array (one-byte uint8_t for n, and then n data |
| | follow) | | | items follow) |
| | | +------------+------------------------------------------------+
| 0x99 | array (two-byte uint16_t for n, and then n data | | 0x99 | array (two-byte uint16_t for n, and then n |
| | items follow) | | | data items follow) |
| | | +------------+------------------------------------------------+
| 0x9a | array (four-byte uint32_t for n, and then n data | | 0x9a | array (four-byte uint32_t for n, and then n |
| | items follow) | | | data items follow) |
| | | +------------+------------------------------------------------+
| 0x9b | array (eight-byte uint64_t for n, and then n data | | 0x9b | array (eight-byte uint64_t for n, and then n |
| | items follow) | | | data items follow) |
| | | +------------+------------------------------------------------+
| 0x9f | array, data items follow, terminated by "break" | | 0x9f | array, data items follow, terminated by |
| | | | | "break" |
| 0xa0..0xb7 | map (0x00..0x17 pairs of data items follow) | +------------+------------------------------------------------+
| | | | 0xa0..0xb7 | map (0x00..0x17 pairs of data items follow) |
| 0xb8 | map (one-byte uint8_t for n, and then n pairs of | +------------+------------------------------------------------+
| | data items follow) | | 0xb8 | map (one-byte uint8_t for n, and then n pairs |
| | | | | of data items follow) |
| 0xb9 | map (two-byte uint16_t for n, and then n pairs of | +------------+------------------------------------------------+
| | data items follow) | | 0xb9 | map (two-byte uint16_t for n, and then n pairs |
| | | | | of data items follow) |
| 0xba | map (four-byte uint32_t for n, and then n pairs of | +------------+------------------------------------------------+
| | data items follow) | | 0xba | map (four-byte uint32_t for n, and then n |
| | | | | pairs of data items follow) |
| 0xbb | map (eight-byte uint64_t for n, and then n pairs of | +------------+------------------------------------------------+
| | data items follow) | | 0xbb | map (eight-byte uint64_t for n, and then n |
| | | | | pairs of data items follow) |
| 0xbf | map, pairs of data items follow, terminated by | +------------+------------------------------------------------+
| | "break" | | 0xbf | map, pairs of data items follow, terminated by |
| | | | | "break" |
| 0xc0 | Text-based date/time (data item follows; see | +------------+------------------------------------------------+
| | Section 3.4.1) | | 0xc0 | Text-based date/time (data item follows; see |
| | | | | Section 3.4.1) |
| 0xc1 | Epoch-based date/time (data item follows; see | +------------+------------------------------------------------+
| | Section 3.4.2) | | 0xc1 | Epoch-based date/time (data item follows; see |
| | | | | Section 3.4.2) |
| 0xc2 | Positive bignum (data item "byte string" follows) | +------------+------------------------------------------------+
| | | | 0xc2 | Positive bignum (data item "byte string" |
| 0xc3 | Negative bignum (data item "byte string" follows) | | | follows) |
| | | +------------+------------------------------------------------+
| 0xc4 | Decimal Fraction (data item "array" follows; see | | 0xc3 | Negative bignum (data item "byte string" |
| | Section 3.4.4) | | | follows) |
| | | +------------+------------------------------------------------+
| 0xc5 | Bigfloat (data item "array" follows; see | | 0xc4 | Decimal Fraction (data item "array" follows; |
| | Section 3.4.4) | | | see Section 3.4.4) |
| | | +------------+------------------------------------------------+
| 0xc6..0xd4 | (tag) | | 0xc5 | Bigfloat (data item "array" follows; see |
| | | | | Section 3.4.4) |
| 0xd5..0xd7 | Expected Conversion (data item follows; see | +------------+------------------------------------------------+
| | Section 3.4.5.2) | | 0xc6..0xd4 | (tag) |
| | | +------------+------------------------------------------------+
| 0xd8..0xdb | (more tags, 1/2/4/8 bytes and then a data item | | 0xd5..0xd7 | Expected Conversion (data item follows; see |
| | follow) | | | Section 3.4.5.2) |
| | | +------------+------------------------------------------------+
| 0xe0..0xf3 | (simple value) | | 0xd8..0xdb | (more tags, 1/2/4/8 bytes and then a data item |
| | | | | follow) |
| 0xf4 | False | +------------+------------------------------------------------+
| | | | 0xe0..0xf3 | (simple value) |
| 0xf5 | True | +------------+------------------------------------------------+
| | | | 0xf4 | False |
| 0xf6 | Null | +------------+------------------------------------------------+
| | | | 0xf5 | True |
| 0xf7 | Undefined | +------------+------------------------------------------------+
| | | | 0xf6 | Null |
| 0xf8 | (simple value, one byte follows) | +------------+------------------------------------------------+
| | | | 0xf7 | Undefined |
| 0xf9 | Half-Precision Float (two-byte IEEE 754) | +------------+------------------------------------------------+
| | | | 0xf8 | (simple value, one byte follows) |
| 0xfa | Single-Precision Float (four-byte IEEE 754) | +------------+------------------------------------------------+
| | | | 0xf9 | Half-Precision Float (two-byte IEEE 754) |
| 0xfb | Double-Precision Float (eight-byte IEEE 754) | +------------+------------------------------------------------+
| | | | 0xfa | Single-Precision Float (four-byte IEEE 754) |
| 0xff | "break" stop code | +------------+------------------------------------------------+
+------------+------------------------------------------------------+ | 0xfb | Double-Precision Float (eight-byte IEEE 754) |
+------------+------------------------------------------------+
| 0xff | "break" stop code |
+------------+------------------------------------------------+
Table 6: Jump Table for Initial Byte Table 6: Jump Table for Initial Byte
Appendix C. Pseudocode Appendix C. Pseudocode
The well-formedness of a CBOR item can be checked by the pseudocode The well-formedness of a CBOR item can be checked by the pseudocode
in Figure 1. The data is well-formed if and only if: in Figure 1. The data is well-formed if and only if:
* the pseudocode does not "fail"; * the pseudocode does not "fail";
* after execution of the pseudocode, no bytes are left in the input * after execution of the pseudocode, no bytes are left in the input
(except in streaming applications) (except in streaming applications)
The pseudocode has the following prerequisites: The pseudocode has the following prerequisites:
* take(n) reads n bytes from the input data and returns them as a * take(n) reads n bytes from the input data and returns them as a
byte string. If n bytes are no longer available, take(n) fails. byte string. If n bytes are no longer available, take(n) fails.
* uint() converts a byte string into an unsigned integer by * uint() converts a byte string into an unsigned integer by
interpreting the byte string in network byte order. interpreting the byte string in network byte order.
skipping to change at page 61, line 49 skipping to change at page 60, line 49
case 5: while (well_formed(true) != -1) well_formed(); break; case 5: while (well_formed(true) != -1) well_formed(); break;
case 7: case 7:
if (breakable) if (breakable)
return -1; // signal break out return -1; // signal break out
else fail(); // no enclosing indefinite else fail(); // no enclosing indefinite
default: fail(); // wrong mt default: fail(); // wrong mt
} }
return 0; // no break out return 0; // no break out
} }
Figure 1: Pseudocode for Well-Formedness Check Figure 1: Pseudocode for Well-Formedness Check
Note that the remaining complexity of a complete CBOR decoder is Note that the remaining complexity of a complete CBOR decoder is
about presenting data that has been decoded to the application in an about presenting data that has been decoded to the application in an
appropriate form. appropriate form.
Major types 0 and 1 are designed in such a way that they can be Major types 0 and 1 are designed in such a way that they can be
encoded in C from a signed integer without actually doing an if-then- encoded in C from a signed integer without actually doing an if-then-
else for positive/negative (Figure 2). This uses the fact that else for positive/negative (Figure 2). This uses the fact that
(-1-n), the transformation for major type 1, is the same as ~n (-1-n), the transformation for major type 1, is the same as ~n
(bitwise complement) in C unsigned arithmetic; ~n can then be (bitwise complement) in C unsigned arithmetic; ~n can then be
skipping to change at page 62, line 32 skipping to change at page 61, line 30
mt = ui & 0x20; // extract major type mt = ui & 0x20; // extract major type
ui ^= n; // complement negatives ui ^= n; // complement negatives
if (ui < 24) if (ui < 24)
*p++ = mt + ui; *p++ = mt + ui;
else if (ui < 256) { else if (ui < 256) {
*p++ = mt + 24; *p++ = mt + 24;
*p++ = ui; *p++ = ui;
} else } else
... ...
Figure 2: Pseudocode for Encoding a Signed Integer Figure 2: Pseudocode for Encoding a Signed Integer
Appendix D. Half-Precision Appendix D. Half-Precision
As half-precision floating-point numbers were only added to IEEE 754 As half-precision floating-point numbers were only added to IEEE 754
in 2008 [IEEE754], today's programming platforms often still only in 2008 [IEEE754], today's programming platforms often still only
have limited support for them. It is very easy to include at least have limited support for them. It is very easy to include at least
decoding support for them even without such support. An example of a decoding support for them even without such support. An example of a
small decoder for half-precision floating-point numbers in the C small decoder for half-precision floating-point numbers in the C
language is shown in Figure 3. A similar program for Python is in language is shown in Figure 3. A similar program for Python is in
Figure 4; this code assumes that the 2-byte value has already been Figure 4; this code assumes that the 2-byte value has already been
skipping to change at page 63, line 32 skipping to change at page 62, line 32
def decode_single(single): def decode_single(single):
return struct.unpack("!f", struct.pack("!I", single))[0] return struct.unpack("!f", struct.pack("!I", single))[0]
def decode_half(half): def decode_half(half):
valu = (half & 0x7fff) << 13 | (half & 0x8000) << 16 valu = (half & 0x7fff) << 13 | (half & 0x8000) << 16
if ((half & 0x7c00) != 0x7c00): if ((half & 0x7c00) != 0x7c00):
return ldexp(decode_single(valu), 112) return ldexp(decode_single(valu), 112)
return decode_single(valu | 0x7f800000) return decode_single(valu | 0x7f800000)
Figure 4: Python Code for a Half-Precision Decoder Figure 4: Python Code for a Half-Precision Decoder
Appendix E. Comparison of Other Binary Formats to CBOR's Design Appendix E. Comparison of Other Binary Formats to CBOR's Design
Objectives Objectives
The proposal for CBOR follows a history of binary formats that is as The proposal for CBOR follows a history of binary formats that is as
long as the history of computers themselves. Different formats have long as the history of computers themselves. Different formats have
had different objectives. In most cases, the objectives of the had different objectives. In most cases, the objectives of the
format were never stated, although they can sometimes be implied by format were never stated, although they can sometimes be implied by
the context where the format was first used. Some formats were meant the context where the format was first used. Some formats were meant
to be universally usable, although history has proven that no binary to be universally usable, although history has proven that no binary
skipping to change at page 66, line 5 skipping to change at page 65, line 5
E.5. Conciseness on the Wire E.5. Conciseness on the Wire
While CBOR's design objective of code compactness for encoders and While CBOR's design objective of code compactness for encoders and
decoders is a higher priority than its objective of conciseness on decoders is a higher priority than its objective of conciseness on
the wire, many people focus on the wire size. Table 7 shows some the wire, many people focus on the wire size. Table 7 shows some
encoding examples for the simple nested array [1, [2, 3]]; where some encoding examples for the simple nested array [1, [2, 3]]; where some
form of indefinite-length encoding is supported by the encoding, form of indefinite-length encoding is supported by the encoding,
[_ 1, [2, 3]] (indefinite length on the outer array) is also shown. [_ 1, [2, 3]] (indefinite length on the outer array) is also shown.
+-------------+--------------------------+--------------------------+ +-------------+----------------------------+----------------+
| Format | [1, [2, 3]] | [_ 1, [2, 3]] | | Format | [1, [2, 3]] | [_ 1, [2, 3]] |
+-------------+--------------------------+--------------------------+ +=============+============================+================+
| RFC 713 | c2 05 81 c2 02 82 83 | | | RFC 713 | c2 05 81 c2 02 82 83 | |
| | | | +-------------+----------------------------+----------------+
| ASN.1 BER | 30 0b 02 01 01 30 06 02 | 30 80 02 01 01 30 06 02 | | ASN.1 BER | 30 0b 02 01 01 30 06 02 01 | 30 80 02 01 01 |
| | 01 02 02 01 03 | 01 02 02 01 03 00 00 | | | 02 02 01 03 | 30 06 02 01 02 |
| | | | | | | 02 01 03 00 00 |
| MessagePack | 92 01 92 02 03 | | +-------------+----------------------------+----------------+
| | | | | MessagePack | 92 01 92 02 03 | |
| BSON | 22 00 00 00 10 30 00 01 | | +-------------+----------------------------+----------------+
| | 00 00 00 04 31 00 13 00 | | | BSON | 22 00 00 00 10 30 00 01 00 | |
| | 00 00 10 30 00 02 00 00 | | | | 00 00 04 31 00 13 00 00 00 | |
| | 00 10 31 00 03 00 00 00 | | | | 10 30 00 02 00 00 00 10 31 | |
| | 00 00 | | | | 00 03 00 00 00 00 00 | |
| | | | +-------------+----------------------------+----------------+
| CBOR | 82 01 82 02 03 | 9f 01 82 02 03 ff | | CBOR | 82 01 82 02 03 | 9f 01 82 02 03 |
+-------------+--------------------------+--------------------------+ | | | ff |
+-------------+----------------------------+----------------+
Table 7: Examples for Different Levels of Conciseness Table 7: Examples for Different Levels of Conciseness
Appendix F. Changes from RFC 7049 Appendix F. Changes from RFC 7049
The following is a list of known changes from RFC 7049. This list is The following is a list of known changes from RFC 7049. This list is
non-authoritative. It is meant to help reviewers see the significant non-authoritative. It is meant to help reviewers see the significant
differences. differences.
* Updated reference for [RFC4627] to [RFC8259] in many places * Updated reference for [RFC4627] to [RFC8259] in many places
skipping to change at page 70, line 14 skipping to change at page 69, line 14
Authors' Addresses Authors' Addresses
Carsten Bormann Carsten Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
D-28359 Bremen D-28359 Bremen
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
EMail: cabo@tzi.org Email: cabo@tzi.org
Paul Hoffman Paul Hoffman
ICANN ICANN
EMail: paul.hoffman@icann.org Email: paul.hoffman@icann.org
 End of changes. 143 change blocks. 
401 lines changed or deleted 404 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/