1 = Project Connected Home over IP
14 *Status:* [red]*Final* / [red]*Active*
20 This document describes the CHIP TLV (_Tag-Length-Value_) format. CHIP
21 TLV is a generalized encoding method for simple structured data. It
22 shares many properties with the commonly used JSON serialization format
23 while being considerably more compact over the wire.
25 == TLV Elements and Encodings
27 Values in the CHIP TLV format are encoded as _TLV elements_. Each TLV
28 element has a type. Element types fall into two categories: _primitive
29 types_ and _container types_. Primitive types convey fundamental data
30 values such as integers and strings. Container types convey collections
31 of elements that themselves are either primitives or containers. The
32 CHIP TLV format supports three different container types: structures,
35 All valid _TLV encodings_ consist of a single top-level element. This
36 value can be either a primitive type or a container type.
40 A TLV element includes an optional numeric tag that identifies its
41 purpose. Two categories of tags are defined: _profile-specific _and
42 _context-specific_. A TLV element without a tag is called an _anonymous_
45 === Profile-Specific Tags
47 Profile-specific tags identify elements globally. A profile-specific tag
48 is a 64-bit number composed of the following fields:
51 * 16-bit profile number
54 Profile-specific tags are defined either by CHIP or by external vendors.
55 Additionally the CHIP Common Profile includes a set of predefined
56 profile-specific tags that can be used across organizations.
58 === Context-Specific Tags
60 Context-specific tags identify elements within the context of a
61 containing structure element. A context-specific tag consists of a
62 single 8-bit tag number. The meaning of a context specific tag derives
63 from the structure it resides in, implying that the same tag number may
64 have different meanings in the context of different structures.
65 Effectively, the interpretation of a context specific tag depends on the
66 tag attached to the containing element. Because structures themselves
67 can be assigned context-specific tags, the interpretation of a
68 context-specific tag may ultimately depend on a nested chain of such
71 Context-specific tags can only be assigned to elements that are
72 immediately within a structure. This implies that an element with a
73 context-specific tag cannot appear as the outermost element of a TLV
78 A special anonymous tag is used to denote TLV elements that lack a tag
79 value. Such a TLV element is referred to as an anonymous element.
81 === Canonical Ordering of Tags
83 Where a distinguished ordering of tags is required (e.g. for the purposes
84 of generating a hash or cryptographic signature of elements within a
85 structure), the following ordering rules shall be used:
87 * Anonymous tags shall be ordered before all other tags.
88 * Context specific tags shall be ordered before profile specific tags.
89 * Context specific tags with numerically lesser tag values shall be ordered
90 before those with higher tag values.
91 * Profile specific tags with numerically lesser vendor ids shall be ordered
92 before those with higher vendor ids.
93 * Profile specific tags with the same vendor id, but numerically lesser
94 profile numbers shall be ordered before those with higher numbers.
98 Depending on its type, a TLV element may contain a length field that
99 gives the length, in bytes, of the element’s value field. A length field
100 is only present for string types (character and byte strings). Other
101 element types either have a predetermined length or are encoded with a
102 marker that identifies their end.
106 The CHIP TLV format supports the following primitive types:
112 * Single or double-precision floating point numbers (IEEE 754-1985
117 Of the primitive types, integers, floating point numbers, booleans and
118 nulls have a predetermined length specified by their type. Byte strings
119 and UTF-8 strings include a length field that gives their lengths in
124 The CHIP TLV format supports the following container types:
130 Each of the container types is a form of element collection that can
131 contain primitive types and/or other container types. The elements
132 appearing immediately within a container type are called its _members_.
133 A container type can contain any number of member elements, including
134 none. Container types can be nested to any depth and in any combination.
135 The end of a container type is denoted by a special element called the
136 ‘end-of-container’ element. Although encoded as a member, conceptually
137 the end-of-container element is not included in the members of the
142 A structure is a collection of member elements that each have a distinct
143 meaning. All member elements within a structure must have a unique tag
144 as compared to the other members of the structure. Member elements
145 without tags (anonymous elements) are not allowed in structures. The
146 encoded ordering of members in a structure may or may not be important
147 depending on the intent of the sender or the expectations of the
148 receiver. For example, in some situations, senders and receivers may
149 agree on a particular ordering of elements to make encoding and decoding
152 Where a distinguished ordering of members is required (for example, for
153 the purposes of generating a hash or cryptographic signature of the
154 structure), the members of the structure shall be encoded in order of
155 their tag values, according to the rules for the canonical ordering of tags.
159 An array is an ordered collection of member elements that either do not
160 have distinct meanings, or whose meanings are implied by their encoded
161 positions in the array. An array can contain any type of element,
162 including other arrays. All member elements of an array must be anonymous
163 elements–that is, they must be encoded with an anonymous tag.
167 A list is an ordered collection of member elements, each of which may be
168 encoded with a tag. The meanings of member elements in a list are denoted
169 by their position within the list in conjunction with any associated tag
172 A list can contain any type of element, including other lists. The members
173 of a list may be encoded with any form of tag, including an anonymous tag.
174 The tags within a list needn’t be unique with respect to other members of
178 **Note:** In a previous version of this specification, the list type was
179 referred to as a “path”. It was subsequently renamed to better reflect its
185 A TLV element is encoded a single control byte, followed by a sequence
186 of tag, length and value bytes. Depending on the nature of the element,
187 any of the tag, length or value fields may be omitted.
191 |Control Byte|Tag|Length|Value
192 |1 byte|0 to 8 bytes|0 to 8 bytes|Variable
195 == Control Byte Encoding
197 The control byte specifies the type of a TLV element and how its tag,
198 length and value fields are encoded. The control byte consists of two
199 subfields: an _element type field_ which occupies the lower 5 bits, and
200 a _tag control field_ which occupies the upper 3 bits.
202 === Element Type Field
204 The element type field encodes the element’s type as well as how the
205 corresponding length and value fields are encoded. In the case of
206 Booleans and the null value, the element type field also encodes the
209 [cols="^1,^1,^1,^1,^1,^1,^1,^1,<8",options="header"]
223 |x|x|x|0|0|0|0|0|Signed Integer, 1-byte value
224 |x|x|x|0|0|0|0|1|Signed Integer, 2-byte value
225 |x|x|x|0|0|0|1|0|Signed Integer, 4-byte value
226 |x|x|x|0|0|0|1|1|Signed Integer, 8-byte value
227 |x|x|x|0|0|1|0|0|Unsigned Integer, 1-byte value
228 |x|x|x|0|0|1|0|1|Unsigned Integer, 2-byte value
229 |x|x|x|0|0|1|1|0|Unsigned Integer, 4-byte value
230 |x|x|x|0|0|1|1|1|Unsigned Integer, 8-byte value
231 |x|x|x|0|1|0|0|0|Boolean False
232 |x|x|x|0|1|0|0|1|Boolean True
233 |x|x|x|0|1|0|1|0|Floating Point Number, 4-byte value
234 |x|x|x|0|1|0|1|1|Floating Point Number, 8-byte value
235 |x|x|x|0|1|1|0|0|UTF-8 String, 1-byte length
236 |x|x|x|0|1|1|0|1|UTF-8 String, 2-byte length
237 |x|x|x|0|1|1|1|0|UTF-8 String, 4-byte length
238 |x|x|x|0|1|1|1|1|UTF-8 String, 8-byte length
239 |x|x|x|1|0|0|0|0|Byte String, 1-byte length
240 |x|x|x|1|0|0|0|1|Byte String, 2-byte length
241 |x|x|x|1|0|0|1|0|Byte String, 4-byte length
242 |x|x|x|1|0|0|1|1|Byte String, 8-byte length
243 |x|x|x|1|0|1|0|0|Null
244 |x|x|x|1|0|1|0|1|Structure
245 |x|x|x|1|0|1|1|0|Array
246 |x|x|x|1|0|1|1|1|List
247 |x|x|x|1|1|0|0|0|End of Container
248 |x|x|x|1|1|0|0|1|Reserved
249 |x|x|x|1|1|0|1|0|Reserved
250 |x|x|x|1|1|0|1|1|Reserved
251 |x|x|x|1|1|1|0|0|Reserved
252 |x|x|x|1|1|1|0|1|Reserved
253 |x|x|x|1|1|1|1|0|Reserved
254 |x|x|x|1|1|1|1|1|Reserved
257 For types that have varying length or value fields, the bottom two bits
258 of the element type field signal the width of the corresponding field as
266 === Tag Control Field
268 The tag control field identifies the form of tag assigned to the element
269 (including none) as well as the encoding of the tag bytes.
271 [cols="^1,^1,^1,^1,^1,^1,^1,^1,<8",options="header"]
285 |0|0|0|x|x|x|x|x|Anonymous, 0 bytes
286 |0|0|1|x|x|x|x|x|Context-specific Tag, 1 byte
287 |0|1|0|x|x|x|x|x|Common Profile Tag, 2 bytes
288 |0|1|1|x|x|x|x|x|Common Profile Tag, 4 bytes
289 |1|0|0|x|x|x|x|x|Implicit Profile Tag, 2 bytes
290 |1|0|1|x|x|x|x|x|Implicit Profile Tag, 4 bytes
291 |1|1|0|x|x|x|x|x|Fully-qualified Tag, 6 bytes
292 |1|1|1|x|x|x|x|x|Fully-qualified Tag, 8 bytes
297 Tags are encoded in 0, 1, 2, 4, 6 or 8 byte widths as specified by the
298 tag control field. Tags consist of up to three numeric fields: a _vendor
299 id field_, a _profile number field_, and a _tag number field_. All
300 fields are encoded in little-endian order.
302 === Fully-Qualified Form
304 A profile-specific tag can be encoded in _fully-qualified form_, where
305 the encoding includes all three tag components (vendor id, profile
306 number and tag number). Two variants of this form are supported, one
307 with a 16-bit tag number and one with a 32-bit tag number. The 16-bit
308 variant must be used with tag numbers < 65536, while the 32-bit variant
309 must be used with tag numbers >= 65536.
313 |Tag Control|Vendor Id Size|Profile Number Size|Tag Number Size|
314 |C0h|2 bytes|2 bytes|2 bytes|For tag numbers < 65536
315 |E0h|2 bytes|2 bytes|4 bytes|For tag numbers >= 65535
320 A profile-specific tag can also be encoded in _implicit form_, where the
321 encoding includes only the tag number, and the vendor id and profile
322 number are inferred from the protocol context in which the TLV encoding
323 is communicated. This form also has two variants based on the magnitude
328 |Tag Control|Tag Number Size|
329 |80h|2 bytes|For tag numbers < 65536
330 |A0h|4 bytes|For tag numbers >= 65535
333 === Common Profile Form
335 A special encoding exists for profile-specific tags that are defined by
336 the CHIP Common Profile. These are encoded in the same manner as
337 implicit tags except that they are identified as common profile tags,
338 rather than implicit profile tags in the tag control field.
342 |Tag Control|Tag Number Size|
343 |40h|2 bytes|For tag numbers < 65536
344 |60h|4 bytes|For tag numbers >= 65535
347 === Context-Specific Form
349 Context-specific tags are encoded as a single byte conveying the tag
354 |Tag Control|Tag Number Size|
355 |20h|1 bytes|All tag numbers 0 - 255
360 Anonymous elements do not encode any tag bytes.
364 |Tag Control|Tag Size|
365 |00h|0 bytes|No data encoded.
370 Length fields are encoded in 0, 1, 2 or 4 byte widths, as specified by
371 the element type field. Length fields of more than one byte are encoded
372 in little-endian order. The choice of width for the length field is up
373 to the discretion of the sender, implying that a sender can choose to
374 send more length bytes than strictly necessary to encode the value.
376 == End of Container Encoding
378 The end of a container type is marked with a special element called the
379 end-of-container element. The end-of-container element is encoded as a
380 single control byte with the value 18h. The tag control bits within the
381 control byte must be set to zero, implying that end-of-container element
382 can never have a tag.
394 An integer element is encoded as follows:
398 |Control Byte|Tag|Value
399 |1 byte|0 to 8 bytes|1, 2, 4 or 8 bytes
402 The number of bytes in the value field is indicated by the element type
403 field within the control byte. The choice of value byte count is at the
404 sender’s discretion, implying that a sender is free to send more bytes
405 than strictly necessary to encode the value. Within the value bytes, the
406 integer value is encoded in little-endian two’s complement format.
408 === UTF-8 and Byte Strings
410 UTF-8 and byte strings are encoded as follows:
414 |Control Byte|Tag|Length|Value
415 |1 byte|0 to 8 bytes|1 to 4 bytes|0 to 2^32^-1 bytes
418 The length field of a UTF-8 or byte string encodes the number of bytes
419 (not characters) present in the value field. The number of bytes in the
420 length field is implied by the type specified in the element type field
421 (within the control byte).
423 For UTF-8 strings, the value bytes must encode a valid UTF-8 character
424 sequence. Senders *should not* include a terminating null character to
425 mark the end of a string. For byte strings, the value can be any
426 arbitrary sequence of bytes.
430 Boolean elements are encoded as follows:
438 The value of a Boolean element (true or false) is implied by the type
439 indicated in the element type field.
441 === Arrays, Structures and Lists
443 Array, structure and list elements are encoded as follows:
447 |Control Byte|Tag|Value|End-of-Container
448 |1 byte|0 to 8 bytes|_Variable_|1-byte
451 The value field of an array/structure/list element is a sequence of
452 encoded TLV elements that constitute the members of the element,
453 followed by an end-of-container element. The end-of-container element
454 must always be present, even in cases where the end of the
455 array/structure/list element could be inferred by other means (e.g. the
456 length of the packet containing the TLV encoding).
458 === Floating Point Numbers
460 A floating point number is encoded as follows:
464 |Control Byte|Tag|Value
465 |1 byte|0 to 8 bytes|4 or 8 bytes
468 The value field of a floating point element contains an IEEE 754-1985
469 single or double precision floating point number encoded in
470 little-endian format (specifically, the reverse of the order described
471 in External Data Representation, RFC 4506). The choice of precision is
472 implied by the type specified in the element type field (within the
473 control byte). The sender is free to choose either precision at their
478 A null value is encoded as follows:
489 [cols="^1,^1,<1,<4",options="header"]
491 |Revision |Date |Modified By |Description
492 |6|2020-05-08|Jay Logue|Renamed path type to list and clarified text in corresponding section.
494 Added section on canonical ordering of tags.
496 Added section describing anonymous tags.
498 Clarified descriptions of structure and array types.
500 Clarified encoding of floating point values with reference to RFC-4506.
501 |5|2020-04-23|Grant Erickson|Import into Project Connected Home over IP.
502 |4|2013-05-20|Jay Logue|Fixed incorrect control byte value for end of container encoding.
503 |3|2013-04-22|Jay Logue|Renamed dictionary to structure.
504 |2|2013-04-17|Jay Logue|Normalized the naming for ‘container’ types.
505 |1|2013-04-15|Jay Logue|Initial revision.
509 _Project Connect Home over IP Public Information_