JSON to TLV and TLV to JSON Converter

Introduction

Helper functions for converting TLV-encoded data to Json format and vice versa.

Supported payloads

The library supports

full bi-directional conversion for matter data model payloads
When the MEI prefix encodes a standard/scoped source, the tag is encoded using ContextSpecific tag if tag_id is less than or equal to UINT8_MAX, and ImplicitProfile tag if tag_id is larger than UINT8_MAX. The reason for allowing such IDs is to support json formats where keys contain ids typically found in paths, like {"1234:INT": 10} meaning "Attribute 1234 has value 10".
When the MEI prefix encodes a manufacturer code, the tag is encoded using FullyQualified_6Bytes tag, the Vendor ID SHALL be set to the manufacturer code, the profile number set to 0 and the tag number set to the MEI suffix.

Format details

In order for the Json format to represent the TLV format without loss of information, the Json name of each element should contain the TLV element tag and type information.

The Json name schema is as follows:

{ [field_name:]field_id:element_type[-sub_element_type] }

Specific rules:

‘element_type’ MUST map to the TLV Type as specified in the table below.
For ‘element_type’ of type “ARRAY”, the sub_element_type MUST always be present and be equal to the ‘element_type’ of the elements in the array.
Array elements MUST have the same ‘element_type’.
Array elements MUST have anonymous TLV tags.
‘field_name’ is always an optional field and can be provided if the semantic name for the field is available.
In the case of an empty array, ‘sub_element_type’ should be “?” (unknown element type).
The unknown element type “?” MUST never occur outside of “ARRAY-?”.
‘field_id’ is equivalent to the Field ID for all cluster payloads (commands, events, attributes), encoded as a decimal number.

The table below summarizes all element types and their corresponding encoding in the Json element name:

TLV Type	element_type	JSON Type
Unsigned Integer ( < 2^32 )	UINT	Number
Unsigned Integer ( >= 2^32 )	UINT	String
Signed Integer ( >= -2^31 and < 2^31 )	INT	Number
Signed Integer ( < -2^31 or >= 2^31 )	INT	String
Boolean	BOOL	Boolean
Float (positive/negative infinity)	FLOAT	String (“Infinity”/“-Infinity”)
Double (positive/negative infinity)	DOUBLE	String (“Infinity”/“-Infinity”)
Float (not infinity)	FLOAT	Number
Double (not infinity)	DOUBLE	Number
Octet String	BYTES	String (Base64 encoded)
UTF-8 String	STRING	String
Null Value	NULL	null
Struct	STRUCT	Dict
Array	ARRAY-sub_element_type	Array
Unknown	?	Empty Array

Note that this is NOT a generalized JSON representation of TLV and does not support arbitrary TLV conversions. The main goal of this Json format is to support data model payloads for events/commands/attributes. Some of the limitations of this format are:

TLV List types are not supported.
TLV Array cannot contain another TLV Array.
The top-level container MUST be an anonymous STRUCT.
Elements of the TLV Structure MUST have Context or Implicit Profile Tags for standard/scoped source and Fully Qualified Profile Tags for an MC source.
Implicit Profile Tag number MUST be larger or equal to 256 and smaller than 2^32 + 1.
TLV Structure element MUST be sorted by tag numbers from low to high, where sorted elements with Context Tags MUST appear first followed by sorted elements with Implicit Profile Tags and then Profile Specific Tags.

Format Example

The following is an example of a Json string. It represents various TLV elements, arrays, and structures.

{                                    // top-level anonymous structure
    "0:ARRAY-STRUCT" : [             // array of structures
        {
            "0:INT" : 8,             // Struct.elem0
            "1:BOOL" : true          // Struct.elem1
        }
    ],
    "1:STRUCT" : {                   // structure
        "0:INT" : 12,                // Struct.elem0
        "1:BOOL" : false,            // Struct.elem1
        "2:STRING" : "example"       // Struct.elem2
    },
    "2:INT" : "40000000000",         // int as string
    "isQualified:3:BOOL" : true,     // boolean with field_name in the Json name
    "4:ARRAY-?" : [],                // empty array
    "5:ARRAY-DOUBLE" : [             // array of doubles
        1.1,
        134.2763,
        -12345.87,
        "Infinity",                  // positive infinity
        62534,                       // positive integer-valued double
        -62534                       // negative integer-valued double
    ],
    "6:ARRAY-BYTES" : [              // array of Octet Strings: [{00 01 02 03 04}, {FF}, {4A EF 88}]
        "AAECAwQ=",                  // base64( {00 01 02 03 04} )
        "/w==",                      // base64( {FF} )
        "Su+I"                       // base64( {4A EF 88} )
    ],
    "7:BYTES" : "VGVzdCBCeXRlcw==",  // base64( "Test Bytes" )
    "8:DOUBLE" : 17.9,               // 17.9 as double
    "9:FLOAT" : 17.9,                // 17.9 as float
    "10:FLOAT" : "-Infinity",        // Negative infinity float
    "4293984426:UINT" : 3,           // Vendor ID = 0xFFF1, Profile ID = 0, Tag ID = 0x00AA
    "contact:11:STRUCT" : {          // structure example with field_name in the Json name
        "name:1:STRING" : "John",
        "age:2:UINT" : 34,
        "approved:3:BOOL" : true,
        "kids:4:ARRAY-INT" : [
            5,
            9,
            10
        ]
    }
}