src/lib/support/jsontlv/README.md

# 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
-   Additional support for generic 32-bit unsigned integer ids using "implicit
    profile tags":

    -   8-bit IDs are encoded as `ContextTags`, which matches matter
        specification for encoding field identifiers
    -   For IDs that are larger, they will be encoded as
        `Implicit Profile Tags`. 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"`.

### 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.
-   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.

## 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
    "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
        ]
    }
}
```