Appendix B: Tag-length-value (TLV) Schema Definitions

 

 

B.1.   Introduction

 

A TLV Schema provides a simple textual description of the structure of data encoded in the Matter TLV format. A single TLV Schema MAY define the structure of multiple different TLV-encoded pay­ loads. This section describes the syntax one can use to define a TLV Schema.

 

B.1.1.  Basic Structure

A TLV Schema takes the form of a series of definitions. Each definition describes some construct, such as a data type. Each definition has an associated human readable name separated from the

definition with a ⇒ symbol. As a mnemonic device, it is useful to read the ⇒ symbol as “is a”. For

example, the following definition defines a data type that MAY be used to represent a sensor sam­

ple:

 

Example

 

/** Sensor sample structure */ sensor-sample => STRUCTURE { timestamp [1] : UNSIGNED INTEGER [ range 32-bits ], value [2] : FLOAT64, }

 

This example would be read as “sensor-sample is a structure containing a timestamp and value“.

 

A TLV Schema MAY contain multiple definitions. The order of definitions within a TLV Schema is unimportant.

 

B.1.2.  Keywords

TLV Schemas employ various keywords when describing a construct. These keywords (e.g. STRUC­ TURE, SIGNED INTEGER, and range) are an inherent part of the schema language. Keywords in TLV Schemas are always case-insensitive. However, by convention, keywords associated with types and

other high-level constructs are capitalized for emphasis in text-only contexts.

 

B.1.3.  Naming

Each definition in a TLV Schema assigns a human-readable name to the construct being defined. This name serves both as a descriptive title as well as a means to refer to the construct from else­ where in the schema.

Names in TLV Schemas are limited to ASCII alphanumeric characters, plus dash (-) and underscore (_). Additionally, all names SHALL begin with either an alphabetic character or an underscore. In general, any name conforming to these rules MAY be used, as long as it does not collide with a key­

 

word used by the schema language.

 

B.1.4.  Namespaces

The name assigned to a schema construct SHALL be unique relative to all other named constructs in the same scope. To facilitate this, TLV Schemas support a namespacing mechanism similar to that provided in languages like C++.

The names of constructs defined within a namespace definition are only required to be unique within the given namespace. Namespaces themselves MAY be nested to any depth.

 

Constructs defined in other namespaces MAY be referenced using a name that gives the enclosing namespaces, plus the construct name, each separated by dots (.). Such a multi-part name is called a scoped name. For example:

 

Namespaces Example

 

namespace a { x => STRING, other-x => b.x } namespace b { x => SIGNED INTEGER }

 

See namespace-def for further details.

 

B.1.5.  Qualifiers

Constructs within a TLV Schema MAY be annotated with additional information using a qualifier. Qualifiers appear within square brackets ([…]) immediately following the construct they affect. In most cases the use of qualifiers is optional, but there are some situations where the schema syntax

requires a qualifier.

 

Often qualifiers are used to place restrictions on the form or range of values that a construct can assume. For example a length qualifier MAY be used to constrain the length of a STRING type:

 

international-standard-book-number => STRING [length 13]

Multiple qualifiers MAY appear within the square brackets, and SHALL be separated by commas. See Section B.5, “Qualifiers” for further details.

 

B.1.6.  Tagging

In a TLV Schema, tag numbers appear as qualifiers attached to a particular named construct, such as a field within a structure. This association reflects the tag’s role as an alias for the textual name in the TLV encoding. The syntax for tag qualifiers is defined in tag. For example:

Tagging Example

 

certificate [my-protocol:1] => STRUCTURE { serial-num [1] : OCTET STRING, … }

 

 

 

B.2.   Definitions

 

A Matter TLV Schema consists of a set of one or more definitions. The definitions that MAY appear within a schema are:

• type-def
• field-group-def
• namespace-def
• protocol-def
• vendor-def

 

B.2.1.  Type Definition (type-def)

Type Definition Syntax

 

type-name [ qualifier ] => type-or-ref type-or-ref: type type-ref type: ANY ARRAY ARRAY OF BOOLEAN CHOICE OF FLOAT32 FLOAT64 LIST LIST OF NULL OCTET STRING SIGNED INTEGER

 

 

STRING STRUCTURE UNSIGNED INTEGER type-ref: type-name scoped-type-name qualifier: tag

 

A type definition associates a name (type-name) with a schema construct representing a TLV type or pseudo-type. The given name serves as a descriptive title for the type, as well as a means to refer to the type from elsewhere in the schema.

Type definitions (type-def) are often used to describe TLV types that appear directly in some form of communication. For example, a type definition MAY define the structure of data carried within the payload of a message. Some type definitions may be used to define general purpose TLV con­

structs which are then employed in the definitions of other types.

The type (type-name) associated with a type definition MAY be any one of the available TLV types or pseudo-type. Alternatively, a type definition MAY contain a scoped type (scoped-type-name) referring to another type definition appearing elsewhere in the schema. This form is referred to as a type ref­ erence (type-ref). The ordering of type definitions and type references within a schema is unimpor­

tant, implying that a type reference MAY refer to a type that is defined later in the schema.

 

A tag qualifier MAY be applied to the name within a type definition to associate a default tag with that name. The default tag will be used in an encoding of the type whenever an explicit tag has not been given.

 

B.2.2.  FIELD GROUP Definition (field-group-def)

FIELD GROUP Definition Syntax

 

field-group-name => FIELD GROUP { field-group-members } field-group-members: field-group-member field-group-members, field-group-member field-group-member: identifier [ id-qualifier ] : type-or-ref                                  // field definition includes field-group-name                                 // field group include id-qualifier: tag                                                                                             // SHALL be present optional

FIELD GROUP declares a collection of fields that MAY be included in a TLV Structure. A FIELD GROUP is

 

never directly encoded in a TLV encoding. A FIELD GROUP is used with includes statement to define common patterns of fields such that they MAY be reused across different STRUCTURE definitions.

A FIELD GROUP definition (field-group-def) contains a list of field definitions, each of which gives the type of the field, its tag, and an associated textual name. The field type MAY be either a fundamen­ tal type, a CHOICE OF pseudo-type, an ANY pseudo-type, or a reference to one of these types defined outside the FIELD GROUP definition.

A FIELD GROUP definition MAY also contain one or more includes statements. Each such statement identifies another FIELD GROUP whose fields are to be included within the referencing FIELD GROUP. Such nested inclusion MAY be specified to any depth.

The rules governing the names and tags associated with fields within a FIELD GROUP are the same as those defined for STRUCTURE.

 

FIELD GROUP Definition Examples

 

common-sensor-sample-fields => FIELD GROUP { timestamp [1]                         : UNSIGNED INTEGER [ range 32-bits ], } temperature-sensor-sample => STRUCTURE [tag-order] { includes common-sensor-sample-fields, value [2]                                   : FLOAT64, } humidity-sensor-sample => STRUCTURE [tag-order] { includes common-sensor-sample-fields, value [2]                                   : UNSIGNED INTEGER [ range 64-bits ], }

 

B.2.3.  Namespace Definition (namespace-def)

Namespace Definition Syntax

 

namespace ns-name { ns-scoped-defs } ns-name: name scoped-name ns-scoped-defs: ns-scoped-def ns-scoped-defs, ns-scoped-def

 

 

ns-scoped-def: type-def field-group-def protocol-def namespace-def

 

namespace introduces a new naming scope. Definitions that appear within the braces of a namespace definition are scoped to that namespace, such that their names need only be unique within the bounds of the enclosing scope. The namespace scoped definitions SHALL be separated

by commas.

 

In general, four forms of definitions MAY appear within a namespace: type definitions (type-def), FIELD GROUP definitions (field-group-def), protocol definitions (protocol-def) and further namespace definitions (namespace-def). Namespace definitions MAY be nested to any level. Protocol defini­

tions, however, are restricted such that they SHALL NOT be nested. Thus a namespace can only con­ tain a protocol definition if the namespace itself is not located, at any level, within another protocol definition.

The name used in a namespace definition MAY be either a simple name, such as a, or a scoped-name, such as a.b.c. When a scoped-name is used, the effect is exactly as if multiple nested namespaces had been declared, each named after a part of the scoped name.

 

It is legal to have multiple namespace definitions, each with the same name, defined within the same scope. The effect is as if there were only a single namespace definition containing a union of the enclosed definitions. Thus, a namespace definition with the same name as a preceding defini­ tion MAY be seen as a kind of continuation of the earlier one.

Namespace Definition Examples

 

namespace abc { property => FLOAT32 [ range 0..50 ], point => STRUCTURE { day [0] : UNSIGNED INTEGER, prop [1] : property } } namespace matter.protocols.aaa { config => STRUCTURE { points [0] : ARRAY OF abc.point, … } }

 

B.2.4.  PROTOCOL Definition (protocol-def)

PROTOCOL Definition Syntax

 

name => PROTOCOL [ qualifier ] { protocol-scoped-defs } qualifier: id   protocol-scoped-defs: protocol-scoped-def protocol-scoped-defs, protocol-scoped-def protocol-scoped-def: type-def field-group-def namespace-def

PROTOCOL defines a Matter protocol. A Matter protocol is a group of logically related Matter TLV con­ structs that together serve a common purpose.

 

Similar to a namespace definition, a PROTOCOL definition introduces a new naming scope in which fur­ ther definitions may appear. The names of definitions appearing within the braces of a PROTOCOL are scoped in exactly the same way as if they had appeared within a namespace definition. Likewise, con­ structs outside the PROTOCOL definition MAY refer to definitions within the protocol by using a scoped name that includes the protocol name. The PROTOCOL scoped definitions SHALL be separated

by commas.

 

PROTOCOL definitions MAY appear at the global naming scope, or within a namespace definition. However, PROTOCOL definitions SHALL NOT be nested within other PROTOCOL definitions at any depth.

Every PROTOCOL definition SHALL include an id qualifier giving the id of the protocol, that uniquely identifies the protocol among all other protocols. The id given in a PROTOCOL definition SHALL be unique relative to all other PROTOCOL definitions in a schema. However, it is legal to have multiple PROTOCOL definitions with the same protocol id, provided that they also have the same name and appear within the same naming scope. The effect of this is as if there were only a single PROTOCOL definition containing a union of the enclosed definitions. This makes it possible to break up a PROTO­ COL definition across multiple schema files.

PROTOCOL Definition Example

 

namespace some.names { my-protocol => PROTOCOL [ VENDOR:0x0008 ] { laser-transducer-metadata [1] => STRUCTURE { serial-num [1] : OCTET STRING, … },

 

 

optics-array [2] => ARRAY OF optical-specification } }

 

B.2.5.  VENDOR Definition (vendor-def)

VENDOR Definition Syntax

 

name => VENDOR [ qualifier ] qualifier: id

 

VENDOR associates a name with a Vendor ID. VENDOR definition SHALL include an id qualifier giving the id of the vendor.

In a TLV Schema that includes a VENDOR definition, the vendor name MAY be used elsewhere in the schema as a stand-in for the associated Vendor ID. One such place where a vendor name may appear is within the id qualifier of a PROTOCOL definition.

VENDOR definitions MAY only appear at the global name scope, implying they SHALL NOT be placed within the body of a namespace or PROTOCOL definition.

Both the name and id value used in a VENDOR definition SHALL be unique across all such definitions. However, for convenience, a VENDOR definition MAY be repeated provided that the name and id are the same.

 

The Matter vendor (0x00000) is implicitly defined in all schemas, although it MAY be explicitly defined as well:

VENDOR Definition Example

 

Matter => VENDOR [ 0x0000 ]

 

 

 

B.3.   Types

 

The TLV format supports 10 fundamental types: integers (signed and unsigned), floats, booleans, UTF-8 strings, octet strings, structures, arrays, lists and nulls. Accordingly, a TLV Schema MAY use one of the following type constructs to constrain an encoding to be one of these fundamental types.

 

B.3.1.  ARRAY / ARRAY OF

ARRAY Syntax

 

ARRAY [ qualifier ] OF type-or-ref                                     // uniform array ARRAY [ qualifier ] { type-pattern }                                    // pattern array

 

 

qualifier (optional): length nullable type-pattern: type-pattern-item type-pattern, type-pattern-item type-pattern-item: type-or-ref quantifier                                                 // unnamed item identifier : type-or-ref quantifier   // named item quantifier (optional): *                                                                                      // zero or more +                                                                                      // one or more { count }                                                                         // exactly count { min..max }                                                                  // between min and max { min.. }                                                                          // at least min

 

ARRAY and ARRAY OF declare an element that is encoded as a TLV Array.

ARRAY OF declares an array where all the items in the array are of the same fundamental type, or taken from the same set of possible types. This form of array is called a uniform array, and is gener­ ally used to represent ordered collections of values.

ARRAY declares an array where the types of the array items follow a particular pattern. In this form, known as a pattern array; the allowed type for an item depends on its position in the array. The overall pattern of types allowed in the array is declared using a schema construct called a linear

type pattern, which is similar to a regular expression (see below). Pattern arrays are typically used to represent vectors, tuples or paths.

A length qualifier on an array MAY be used to constraint the minimum and maximum number of items in the array. For a pattern array, the given length constraint SHALL be consistent with (i.e. fall within) the minimum and maximum number of items implied by the type pattern. In cases where

the length qualifier places a narrower constraint on the length of an array than that implied by the type pattern, the length qualifier constraint takes precedence.

A nullable qualifier MAY be used to indicate that a TLV Null MAY be encoded in place of the ARRAY or ARRAY OF. Note that an array that has been replaced by a Null is distinct in terms of its encoding from an array that has no items.

 

B.3.1.1.  Linear Type Patterns

A linear type pattern describes the sequence of TLV types that MAY appear in a TLV Array or List element. In its simplest form, a linear type pattern is a list of type definitions, or references to defined types, where each item constrains the TLV type that appears at the corresponding position in the collection. The type pattern is always anchored at the start of the collection, with the first type constraining the first item in the collection. Any type or pseudo-type MAY appear within a lin­ ear type pattern.

 

More complex type patterns can be created by using a quantifier. Quantifiers appear after a type in

a type pattern and specify the number of times the associated type MAY appear at that position in the collection. Quantifiers borrow common regular expression notation to denote repetition, with * meaning zero or more,  + meaning one or more, and  { } expressing specific counts. Using  quanti­

fiers, one can express complex sequences of types, including some that require arbitrary look- ahead to match.

 

B.3.1.2.  Item Names

Items or groups of items in a pattern array MAY be given textual names. These names do not affect the encoding of the array, but serve as user documentation, or as input to code generation tools. Item names within a pattern array SHALL be unique.

Per the rules for encoding TLV arrays, array items SHALL NOT have tags. Thus the tag qualifier SHALL NOT be applied to an item name with a pattern array.

ARRAY Example

 

supported-country-codes => ARRAY [ length 0..10 ] OF STRING [ length 2 ] weather-tuple => ARRAY { timestamp                        : UNSIGNED INTEGER [ range 32-bits ], temperature          : FLOAT64, relative-humidity             : UNSIGNED INTEGER [ range 0..100 ], precipitation      : UNSIGNED INTEGER [ range 0..100 ], } named-vector => ARRAY { name                                  : STRING, FLOAT64 *, }

 

B.3.2.  BOOLEAN

BOOLEAN Syntax

 

BOOLEAN [ qualifier ] qualifier (optional): nullable

BOOLEAN declares an element that SHALL be encoded as a TLV Boolean. If the nullable qualifier is given, a TLV Null MAY be encoded in its place.

 

BOOLEAN Example

 

pathlight-enabled => BOOLEAN

 

B.3.3.  FLOAT32 / FLOAT64

FLOAT Syntax

 

FLOAT32 [ qualifier ] FLOAT64 [ qualifier ]   qualifier (optional): range nullable

 

FLOAT32 declares an element that SHALL be encoded as a TLV floating point number with the ele­ ment type indicating a 4-octet IEEE 754-2019 single-precision value. Correspondingly, FLOAT64

declares a TLV element that SHALL be encoded as a TLV floating point number with the element type indicating an 8-octet IEEE 754-2019 double-precision value.

If the nullable qualifier is given, a TLV Null MAY be encoded in place of the number.

 

The allowed range of values can be constrained using the range qualifier. If omitted, the value is constrained by what the relevant TLV type can represent.

FLOAT Example

 

set-value => FLOAT32 [ range 0..50 ]

 

B.3.4.  SIGNED INTEGER / UNSIGNED INTEGER

Integer Syntax

 

SIGNED INTEGER [ qualifier ] { enum } UNSIGNED INTEGER [ qualifier ] { enum }   qualifier (optional): range nullable enum: identifier = int-value

SIGNED INTEGER declares an element that SHALL be encoded as a TLV integer with the element type indicating the integer is signed. Correspondingly, UNSIGNED INTEGER declares a TLV element that SHALL be encoded as a TLV integer with the element type indicating the integer is unsigned.

 

If the nullable qualifier is given, a TLV Null MAY be encoded in place of the integer.

 

The allowed range of values MAY be constrained using the range qualifier. If omitted, the value is constrained by what the relevant TLV type can represent.

SIGNED INTEGER and UNSIGNED INTEGER definitions MAY include a set of enumerated values (enum), each of which associates a textual name (identifier) with a constant integer value (int-value). Each value SHALL conform to the allowed range of values for the SIGNED INTEGER definition as given by its sign and any range qualifier. The presence of enumerated values SHALL NOT restrict senders to

only encoding those values. Rather, enumerations merely give symbolic names to particular note­ worthy values.

Integer Examples

 

sensor-value => SIGNED INTEGER [ range -100..100 ] counter => UNSIGNED INTEGER [ range 32-bits ]

 

B.3.5.  LIST / LIST OF

LIST Syntax

 

LIST [ list-qualifier ] OF type-or-ref                                            // uniform list LIST [ list-qualifier ] { type-pattern }                      // pattern list   list-qualifier (optional): length nullable type-pattern: type-or-ref quantifier                                                                          // unnamed item identifier [ qualifier ] : type-or-ref quantifier       // named item quantifier (optional): *                                                                                               // zero or more +                                                                                               // one or more { count }                                                                                  // exactly count { min..max }                                                                           // between min and max { min.. }                                                                                   // at least min qualifier (optional): tag

LIST and LIST OF declare an element that is encoded as a TLV List. LIST and LIST OF declare the same fundamental type, but differ based on how the allowed types of their items are expressed.

LIST OF declares a list where all the items in the list are of the same fundamental type, or taken from the same set of possible types. This form of list is called a uniform list. Uniform lists are gener­ ally used to represent ordered collections of values where the tags differentiate the semantic mean­

ing of the value.

 

LIST declares a pattern list where the types of the items in the list follow a particular pattern. In this form, the allowed type(s) for an item depends on its position in the array. Pattern lists are typically used to represent path-like constructs.

 

The overall pattern of types allowed in a pattern list is declared using a schema construct called a linear type pattern. The syntax and interpretation of linear type patterns for pattern lists are the same as those for pattern arrays (see Section B.3.1.1, “Linear Type Patterns”).

The length qualifier MAY be used to constraint the minimum and maximum number of items in the list. For a pattern list, the given length constraint SHALL be consistent with (i.e. fall within) the min­

imum and maximum number of items implied by the type pattern. In cases where the length quali­

fier places a narrower constraint on the length of a list than that implied by the type pattern, the

length qualifier constraint takes precedence.

A nullable qualifier MAY be used to indicate that a TLV Null MAY be encoded in place of the LIST or LIST OF. Note that a list that has been replaced by a Null is distinct (in terms of its encoding) from a list that has no items.

 

B.3.5.1.  Item Names

As with the ARRAY type, items or groups of items in a pattern list MAY be given textual names to dis­ tinguish their purposes. Item names within a pattern list SHALL be unique.

 

B.3.5.2.  Item Tags

Items within a pattern list can have a tag qualifier that specifies a particular tag value that SHALL be encoded with the item. The specific tag can be protocol-specific or context-specific, or the anony­ mous tag. The assigned tag values are not required to be unique among the items in a pattern list.

When no explicit tag qualifier is given (which is always the case for uniform lists) the items in a list automatically assume the default tag of their underlying types, if such a tag is provided. This can occur in two situations: 1) when the underlying type is a reference to a type definition that declares

a default tag, and 2) when the underlying type is a CHOICE OF whose alternates declare default tags.

See default tag for further information.

 

If no tag qualifier is given, and no default tag is available, an encoder is allowed to encode list items with any tag of their choosing.

 

B.3.6.  OCTET STRING

OCTET STRING Syntax

 

OCTET STRING [ qualifier ] qualifier (optional): length nullable

OCTET STRING declares an element that is encoded as a TLV Octet String, and in particular with the element type indicating it’s an Octet String.

 

The minimum and maximum number of bytes can be constrained using the length qualifier.

 

OCTET STRING Example

 

address => OCTET STRING [ length 8 ]

 

B.3.7.  NULL

NULL Syntax

 

NULL

 

NULL declares an element that SHALL be encoded as a TLV Null. There are no qualifiers that can be associated with a NULL type.

NULL Example

 

serial-num => CHOICE OF { STRING, UNSIGNED INTEGER, NULL }

 

B.3.8.  STRING

STRING Syntax

 

STRING [ qualifier ] qualifier (optional): length nullable

STRING declares an element that is encoded as a TLV UTF-8 String, and in particular with the ele­ ment type indicating it’s a UTF-8 String.

 

If the nullable qualifier is given, a TLV Null MAY be encoded in place of the string.

 

The minimum and maximum length of the string can be constrained using the length qualifier.

 

STRING Example

 

name-field => STRING [ length 0..32 ]

 

B.3.9.  STRUCTURE

STRUCTURE Syntax

 

STRUCTURE [ structure-qualifier ] { structure-fields } structure-qualifier (optional): extensible

 

 

order nullable   structure-fields: structure-field structure-fields, structure-field structure-field: identifier [ id-qualifier ] : type-or-ref                                  // field definition includes field-group-name                                                   // field group include id-qualifier: tag optional

 

STRUCTURE declares an element that is encoded as a TLV Structure. The STRUCTURE fields SHALL be separated by commas.

A STRUCTURE definition declares the list of fields that MAY appear within the corresponding TLV Structure. Each field definition gives the type of the field, its tag, and an associated textual name. The field type MAY be either a fundamental type, a CHOICE OF pseudo-type, an ANY pseudo-type, or a reference to one of these types defined outside the STRUCTURE definition.

A STRUCTURE definition MAY also contain one or more includes statements. Each such statement identifies a FIELD GROUP definition whose fields are to be included within the TLV Structure as if they had been declared within the STRUCTURE definition itself (see Includes FIELD GROUP below).

 

An extensible qualifier MAY be used to declare that a structure can be extended at encoding time by the inclusion of fields not listed in the STRUCTURE definition.

The order qualifiers (any-order, schema-order and tag-order) MAY be used to specify a particular order for the encoding of fields within a TLV Structure.

 

A nullable qualifier MAY be used to indicate that a TLV Null MAY be encoded in place of the STRUC­ TURE.

 

B.3.9.1.  Fields

Fields within a STRUCTURE are assigned textual names to distinguish them from one another. Each such name SHALL be distinct from all other field names defined within the STRUCTURE or included via a includes statement. Fields names do not affect the encoding of the resultant TLV, but MAY

serve as either user documentation or input to code generation tools.

 

Per the rules of TLV, all fields within a TLV Structure SHALL be encoded with a distinct TLV tag. Field tags are declared by placing a tag qualifier on the field name. Both protocol-specific and con­

text-specific tags are allowed on the fields in a STRUCTURE definition.

For a given field if the tag qualifier is missing then the underlying type SHALL provide a default tag. This can occur in two situations:

 

1. the underlying type is a reference to a type definition that provides a default tag
2. the underlying type is a CHOICE OF pseudo-type whose alternates provide default tags. The tags associated with includes fields are inherited from the target FIELD GROUP

All tags associated with the fields of a TLV Structure SHALL be unique. This is true not only for tags declared directly within the STRUCTURE definition, but also for any tags associated with fields that are incorporated via an includes statement.

The anonymous tag SHALL NOT be used as the tag for a field within a STRUCTURE definition.

The optional qualifier MAY be used to declare a field which can be omitted from the structure encoding under some circumstances.

 

B.3.9.2.  CHOICE OF Fields

A field within a STRUCTURE definition MAY be defined to be a CHOICE OF (either directly within the STRUCTURE definition or via a type reference). Over the wire, such a field is encoded as one of the alternate types given in the CHOICE OF definition. For example, the user-id field in the following STRUCTURE MAY be encoded as either a TLV UTF-8 String or an Unsigned Integer.

STRUCTURE with CHOICE OF Field Example

 

user-information => STRUCTURE [ extensible ] { user-id [1] : CHOICE OF { UNSIGNED INTEGER, STRING } }

If a tag qualifier is given for a CHOICE OF field (e.g. [1] as shown above), that tag SHALL be used in the encoding of the field for all possible alternates. On the other hand, if a tag qualifier is not given, then the default tag associated with the selected CHOICE OF alternate SHALL be used in the encoding. For example, in the following structure, a context-tag of 1 will be encoded if the user-id field is an Unsigned Integer, or 2 if the field is a String.

STRUCTURE with CHOICE OF Field with Default Tag Example

 

user-information => STRUCTURE [ extensible ] { user-id : CHOICE OF { id [1] : UNSIGNED INTEGER, name [2] : STRING } }

 

Note that, in all cases, the tag or tags associated with a CHOICE OF field SHALL be unique within the context of the containing STRUCTURE.

 

B.3.9.3.  Includes FIELD GROUP

A includes statement MAY be used within a STRUCTURE definition to incorporate the fields of a FIELD GROUP defined outside the STRUCTURE. The fields of the FIELD GROUP are included in the STRUCTURE as if they had been listed within the STRUCTURE definition itself.

A particular FIELD GROUP SHALL NOT be included more than once within a given STRUCTURE.

The names assigned to fields within an included FIELD GROUP SHALL be distinct with respect to all other fields contained within the enclosing STRUCTURE, whether defined directly within the STRUCTURE itself, or included from another FIELD GROUP.

Likewise, tags assigned to fields within an included FIELD GROUP SHALL be distinct with respect to all other fields within the enclosing STRUCTURE.

 

 

 

B.4.   Pseudo-Types

 

Pseudo-types are type-like constructs that provide flexibility in schema definitions. Some pseudo- types, like CHOICE OF and ANY, allow for variance in the fundamental TLV types that may appear in an encoding. Others make it easier to reuse schema constructs in multiple contexts.

 

B.4.1.  ANY

ANY Syntax

 

ANY

ANY declares an element that can be encoded as any fundamental TLV type. Note that ANY is not a fundamental TLV type itself, but rather a pseudo-type that identifies a range of possible encodings. An ANY type serves a shorthand for (and is exactly equivalent to) a CHOICE OF all possible fundamen­ tal types.

There are no qualifiers that can be associated with an ANY type.

ANY Example

 

app-defined-metadata => ANY

 

B.4.2.  CHOICE OF

CHOICE OF Syntax

 

CHOICE [ qualifier ] OF { alternates } qualifier (optional): nullable

 

 

alternates: alternate alternates, alternate alternate: type-or-ref                                                                               // unnamed alternate identifier [ id-qualifier ] : type-or-ref                                  // named alternate id-qualifier: tag

 

CHOICE OF declares an element that MAY be any of a set of TLV types. CHOICE OF is considered a pseudo-type, rather than a fundamental type, in that the CHOICE OF itself doesn’t have a representa­ tion in the final TLV encoding.

 

The allowed TLV types for a CHOICE OF, known as alternates, are given in the body of the definition. An alternate MAY be any of the fundamental TLV types, an ANY pseudo-type, or another CHOICE OF definition (more on this below). Additionally, an alternate MAY be a type reference (in the form of a scoped type name) referring to a type defined outside of the CHOICE OF definition.

A nullable qualifier MAY be used to indicate that a TLV Null can be encoded in place of the CHOICE OF. This is exactly the same as if NULL had been listed as one of the alternates.

 

B.4.2.1.  Alternate Names and Tags

 

Alternates MAY be assigned textual names to distinguish them from one another. Each such name SHALL be unique within the particular CHOICE OF definition. Alternate names do not affect the encoding of the resultant TLV. Rather, alternate names serve as user documentation, or as input to

code generation tools.

 

Named CHOICE OF alternates MAY include at tag qualifier assigning a particular tag value to the alternate. When qualified in this way, the given tag value serves as a default tag for the alternate whenever the CHOICE OF appears in a context that doesn’t otherwise specify a tag. The tags assigned within a CHOICE OF do not need to be unique, although see the discussion of Ambiguous Alternates

below.

Both protocol-specific and context-specific tags are allowed on the alternates of a CHOICE OF defini­ tion.

 

B.4.2.2.  Nested CHOICE OF and CHOICE OF Merging

It is legal for an alternate within a CHOICE OF to be another CHOICE OF definition, or a type reference to such. In this case, the effect is exactly as if the alternates of the inner CHOICE OF definition had been declared directly with the outer definition. This merging of CHOICE OF alternates occurs to any level of nesting, and MAY be used as a means of declaring multiple CHOICE OF that are supersets of other CHOICE OF.

 

When alternates are merged, their names are preserved. In cases where the same name appears in nested CHOICE OF definitions, the name of the outer alternate is prepended to that of the inner alter­

 

nate, separated by a dot, to form a unique name for the merged alternate. In these cases, the outer alternate SHALL have a name in the schema, to ensure uniqueness.

An example of invalid CHOICE OF syntax, which results in a name conflict when alternates are merged:

 

CHOICE OF Invalid Alternates Merge Example

 

CHOICE OF { CHOICE OF { foo: STRING, bar: UNSIGNED INTEGER }, CHOICE OF { foo: BOOLEAN, bar: FLOAT64 } }

 

The example below shows how a valid schema should look to avoid conflict:

 

CHOICE OF Valid Alternates Merge Example

 

CHOICE OF { alt1: CHOICE OF { foo: STRING, bar: UNSIGNED INTEGER }, alt2: CHOICE OF { foo: BOOLEAN, bar: FLOAT64 } }

 

B.4.2.3.  Ambiguous Alternates

A CHOICE OF MAY contain multiple alternates having the same fundamental TLV type (e.g. two alter­ nates that are both SIGNED INTEGER). If these alternates are also encoded using the same tag, their encoded forms are effectively indistinguishable from one another. Such alternates are referred to

as ambiguous alternates.

Ambiguous alternates MAY occur due to the merging of nested CHOICE OF definitions (see above). They MAY also arise in cases where the tags associated with the alternates are overridden by a tag qualifier in an outer context; e.g. when a STRUCTURE incorporates a CHOICE OF field that has a specific tag qualifier assigned to the field.

 

Ambiguous alternates are legal in TLV Schemas. However, care SHALL be taken when introducing ambiguous alternates to ensure that a decoder can correctly interpret the resulting encoding. This can be achieved, for example, by signaling the appropriate interpretation via a data value (e.g. an

 

enumerated integer) contained elsewhere in the encoding.

 

 

 

B.5.   Qualifiers

 

Qualifiers are annotations that provide additional information regarding the use or interpretation of a schema construct. Often qualifiers are used to place restrictions on the form or range of values that the construct can assume.

 

B.5.1.  any-order / schema-order / tag-order

Order Qualifiers Syntax

 

STRUCTURE [ any-order ] STRUCTURE [ schema-order ] STRUCTURE [ tag-order ]

 

The any-order, schema-order and tag-order qualifiers MAY be used to specify a particular order for the encoding of fields within a STRUCTURE.

The any-order qualifier specifies that the encoder of a TLV structure is free to encode the fields of the structure in any desired order.

 

The schema-order qualifier specifies that the fields of a structure SHALL be encoded in the order given within the associated STRUCTURE definition. If the STRUCTURE definition contains one or more includes statements, the fields of the referenced FIELD GROUPs SHALL be encoded in the order given in the respective FIELD GROUP definition, and at the position of the includes statement relative to other fields within the STRUCTURE.

The tag-order qualifier specifies that the fields of a structure SHALL be encoded in the order speci­ fied by their tags, as defined in Section A.2.4, “Canonical Ordering of Tags”.

Only a single ordering qualifier MAY be applied to a given STRUCTURE type.

In the absence of an order qualifier, fields within TLV structure MAY generally be encoded in any order. However, the author of a STRUCTURE definition MAY choose to impose custom ordering con­ straints on some or all of the fields if so desired. Such constraints SHALL be clearly described in the

prose documentation for the schema.

 

B.5.2.  extensible

extensible Qualifier Syntax

 

STRUCTURE [ extensible ]

The extensible qualifier is only allowed on STRUCTURE types, and declares that the structure MAY be extended by the inclusion of fields not listed in its definition. When a structure is extended in this

way, any new fields that are included SHALL use tags that are distinct from any of those associated with defined or included fields.

 

Absent the extensible qualifier, a structure encoding SHALL NOT include fields beyond those given in the STRUCTURE definition.

extensible Qualifier Example

 

user-information => STRUCTURE [ extensible ] { user-id [1]                          : UNSIGNED INTEGER, first-name [2]                   : STRING, last-name [3]                                       : STRING, email-address [4]          : STRING, }

 

B.5.3.  id

id Qualifier Syntax

 

vendor-name => VENDOR [ id uint-value ] protocol-name => PROTOCOL [ id uint-value ] protocol-name => PROTOCOL [ id uint-value:uint-value ] protocol-name => PROTOCOL [ id vendor-name:uint-value ]

The id qualifier is used to specify an identifying number associated with a VENDOR or PROTOCOL defini­ tion.

 

When applied to a VENDOR definition, the id value is a 16-bit unsigned integer specifying the Protocol Vendor ID, which uniquely identify an organization or company. VENDOR ids are used to scope other identifiers (e.g. PROTOCOL ids) such that organizations can independently mint these identifiers with­

out fear of collision.

When applied to a PROTOCOL definition, the id value MAY take three forms:

• 32-bit unsigned integer, which is composed of a Protocol Vendor ID in the high 16-bits and a protocol id in the low 16-bits
• two 16-bit unsigned integers (separated by a colon) specifying the Protocol Vendor ID and proto­ col id
• vendor-name and 16-bit protocol id (separated by a colon). The vendor-name definition SHALL exist elsewhere in the schema

 

id Qualifier Examples

 

MATTER-VENDOR-AB => VENDOR [ 0x00AB ] // Equivalent definitions of the protocol introduced by MATTER-VENDOR-AB vendor-ab-prot8 => PROTOCOL [ 0x00AB0008 ]   vendor-ab-prot8 => PROTOCOL [ 0x00AB:0x0008 ]

 

 

vendor-ab-prot8 => PROTOCOL [ MATTER-VENDOR-AB:8 ]

 

B.5.4.  length

length Qualifier Syntax

 

type [ length count ]                                  // exactly count type [ length min..max ]                           // between min and max (inclusive) type [ length min.. ]                                              // at least min

 

The length qualifier MAY be used to constrain the number of elements in a collection type, such as an ARRAY or LIST, or the number of bytes in a STRING or OCTET STRING type.

 

B.5.5.  nullable

nullable Qualifier Syntax

 

type [ nullable ]

The nullable qualifier is used with ARRAY, LIST, STRUCTURE, STRING, OCTET STRING, BOOLEAN, SIGNED INTE­ GER, UNSIGNED INTEGER, FLOAT32, FLOAT64 types. The nullable qualifier declares that a TLV Null MAY be substituted for a value of the specified type at a particular point in an encoding. For example, in the

following sensor-sample structure, a null value MAY  be encoded for the value field (e.g. in the  case

the sensor was off-line at the sample time):

 

nullable Qualifier Example

 

sensor-sample => STRUCTURE { timestamp [1] : UNSIGNED INTEGER, value [2]         : FLOAT64 [ nullable ], }

Applying a nullable qualifier to a type is exactly the same as defining a CHOICE OF type with alter­ nates for the primary and NULL. For example, the sensor sample structure could also be defined as follows:

 

nullable Qualifier Example

 

sensor-sample => STRUCTURE { timestamp [1] : UNSIGNED INTEGER, value [2] : CHOICE OF { FLOAT64, NULL }

 

 

}

 

B.5.6.  optional

optional Qualifier Syntax

 

… field-name [ optional ] : type-or-ref, …

 

The optional qualifier declares that a field within a STRUCTURE or FIELD GROUP is optional, and MAY be omitted by an encoder. The optional qualifier MAY only appear on the name portion of a field definition within either a STRUCTURE or FIELD GROUP.

Note that an optional field is distinct, both semantically and in terms of encoding, from a field whose type has been declared nullable. In the former case the field MAY be omitted from the encod­ ing altogether. In the latter case the field SHALL appear within the encoding, however its value

MAY be encoded as a TLV Null. It is legal to declare a field that is both optional and nullable.

The conditions under which an optional field can be omitted depend on the semantics of the struc­ ture. In some cases, fields MAY be omitted entirely at the discretion of the sender. In other cases, omission of a field MAY be contingent on the value present in another field. In all cases, prose docu­ mentation associated with the field definition SHALL make clear the rules for when the field may be omitted.

Optional fields are allowed within FIELD GROUP and retain their optionality when included within

STRUCTURE.

optional Qualifier Example

 

user-information => STRUCTURE [ extensible ] { user-id [1]                                           : UNSIGNED INTEGER, first-name [2]                                     : STRING, middle-name [3, optional]              : STRING,                                               // MIGHT be omitted last-name [4]    : STRING, email-address [5, optional] : STRING,                                   // MIGHT be omitted }

 

B.5.7.  range

range Qualifier Syntax

 

integer-type [ range min..max ]                                       // explicit constraint (inclusive) integer-type [ range 8-bits ]       // width constraint integer-type [ range 16-bits ] integer-type [ range 32-bits ] integer-type [ range 64-bits ]

 

The range qualifier MAY be used to constrain the range of values for a numeric type such as SIGNED INTEGER, UNSIGNED INTEGER, FLOAT32, or FLOAT64. Two forms are supported: explicit constraints and width constraints. Only one form MAY be applied to a given type.

 

An explicit constraint gives specific minimum and maximum (inclusive) values for the type. These MAY be any value that is legal for the underlying type.

 

A width constraint constrains the value to fit within a specific number of bytes. Any of the width constraints (8-bits, 16-bits, 32-bits or 64-bits) MAY be applied to SIGNED INTEGER and UNSIGNED INTEGER types, where 8-bits, 16-bits, 32-bits and 64-bits constraints correspond to 1-octet, 2-octet, 4-octet and

8-octet element type respectively; only 32-bits constraint MAY be applied to FLOAT32 type and only 64-bits constraint MAY be applied to FLOAT64 type.

Note that a width constraint range qualifier does not obligate an encoder to always encode the spec­ ified number of bits. Per the TLV encoding rules, senders are always free to encode integer and floating point values in any encoding size, bigger or smaller, that will accommodate the value.

 

range Qualifier Example

 

system-status-event => STRUCTURE { timestamp [1]                           : UNSIGNED INTEGER [ range 32-bits ], num-processes [2] : UNSIGNED INTEGER [ range 16-bits ], percent-busy [3] : UNSIGNED INTEGER [ range 0..100 ], }

 

B.5.8.  tag

tag Qualifier Syntax

 

identifier [ tag-num ]                                                     // context-specific tag identifier [ protocol-id:tag-num ] // protocol-specific tag identifier [ protocol-name:tag-num ] // protocol-specific tag identifier [ *:tag-num ]                                                 // protocol-specific tag (cur. protocol) identifier [ anonymous ]                                               // no tag

The tag qualifier is allowed on type names, field names within a STRUCTURE (STRUCTURE Fields) or FIELD GROUP, item names within a LIST (LIST Item Tags), alternate names within a CHOICE OF (CHOICE OF Fields).

 

The tag qualifier specifies a numeric tag value to be used when encoding a particular value. For  brevity, the tag keyword SHALL be omitted when specifying a tag qualifier. As a special case, the keyword anonymous MAY be used to signal a value that SHALL be encoded without a tag.

 

Matter TLV supports two forms of tags: Protocol-Specific Tags and Context-Specific Tags. A protocol- specific tag is a colon-separated tuple containing a protocol-id and a tag-num. Protocol ids MAY also be specified indirectly, by giving the name of a PROTOCOL definition (protocol-name) located else­ where in the schema. An asterisk (*) MAY be used as a shorthand to refer to the id of the PROTOCOL definition in which the tag qualifier appears. This protocol is referred to as the current protocol.

 

B.5.8.1.  Explicit Tags

A tag qualifier that appears on a field within a STRUCTURE or FIELD GROUP, or on an item within a LIST, specifies the exact tag to be used when encoding the associated field/item. Such a tag is called an explicit tag, and MAY be either a context-specific, protocol-specific or anonymous (for LIST) tag.

If a field or item lacks a tag qualifier, then the encoding will use a default tag associated with the underlying field type, if such a tag has been specified.

 

B.5.8.2.  Default Tags

A tag qualifier that appears on a type definition, or on an alternate within a CHOICE OF, serves as a default tag. A default tag is used to encode a value when an explicit tag has not been given in the schema.

 

For example, a field within a STRUCTURE that refers to a type with a default tag will use that tag if no tag qualifier has been specified on the field itself. Similarly, tag qualifiers that appear on the alter­ nates of a CHOICE OF serve as default tags to be used when no other tag has been specified.

Both context-specific and protocol-specific tags MAY be used as default tags. ‘anonymous` tag SHALL NOT be used as default tag.

 

Default Tag Qualifier Example

 

vendor-ab-prot8 => PROTOCOL [ id 0x00AB0008 ] { ec-pub-key [0x00AB0008:1] => OCTET STRING,                // default protocol-specific tag using // a numeric protocol id ec-priv-key [vendor-ab-prot8:2] => STRUCTURE // default protocol-specific // tag using a name { priv-key [1]                 : OCTET STRING,                       // explicit context-specific tag pub-key [2, optional] : ec-pub-key                             // explicit tag overrides default tag on // ec-pub-key curve                           : CHOICE OF                               // tag depends on choice of id or name { id [3]                   : UNSIGNED INTEGER,             // default tag if id chosen name [4]                                     : STRING               // default tag if name chosen } }, ecdsa-sig [*:3] => STRUCTURE                                              // shorthand for vendor-ab-prot8:3 { r [1]                              : OCTET STRING, s [2]                              : OCTET STRING } } // end vendor-ab-prot8 PROTOCOL

 

B.5.9.  Documentation and Comments

TLV Schemas MAY include inline annotations that support the automatic generation of reference documentation and the production of documented code. TLV Schemas follow the Javadoc style of

annotation wherein documentation is wrapped in the special multi-line comment markers /** and

*/.

Documentation and Comments Example

 

/** Sensor sample structure */ sensor-sample => STRUCTURE { timestamp [1] : UNSIGNED INTEGER, value [2] : FLOAT64, }

In certain cases, documentation MAY also be placed after a construct, using /**< and */.

Documentation and Comments for a Construct Example

 

/** Sensor sample structure */ sensor-sample => STRUCTURE { timestamp [1] : UNSIGNED INTEGER, /**< Unix timestamp */ value [2] : FLOAT64,                                                                           /**< Sensor value */ }

Postfix annotations are allowed on STRUCTURE and FIELD GROUP members, ARRAY and LIST items,

CHOICE OF alternates, SIGNED INTEGER and UNSIGNED INTEGER enumerated values.

Non-documentation comments follow the standard C++ commenting style.

 

Documentation and Comments C++ Style Example

 

user-information => STRUCTURE [ extensible ] { user-id [1]                          : UNSIGNED INTEGER, // 0 = Unknown user id first-name [2]   : STRING, last-name [3]                                       : STRING, email-address [4]          : STRING, /* TODO: additional fields to be added later */ }