[core] YANG list to CBOR mapping

[peter van der Stok <[e-mail]>]

Hi CoOL authors,

This e_mail complements my earlier e-mail on YANG to CBOR mapping, and 
explains the proposed list encoding.

Both the draft yang-json and the CoOL draft encode a list as an array. 
In the yang-json case as a JSON array, and in the CoOL case as major 
type 4 of major type 5 objects.
This encoding prevents the selection of list instances on the basis of 
the key values from the payload alone. In CoMI the list is encoded as a 
major type 5 of major type 5 objects. This deviation from the yang-json 
mapping is motivated by the wish to transport individual list instances 
and identify the instances in the payload from the key values. This is 
especially important in case of PATCH operation on list instances.
Two cases are to be looked at: (1) the list definition specifies one or 
more key elements, and (2) the list definition does not specify a key 
element. We will start with a list containing key elements.
It is the wish to transport only those list elements with a unique key 
value, either to support a PATCH or a FETCH command. Therefore it is 
required that the payload allows the selection and identification of 
these list element on the basis of their key values. Using the 
diagnostic JSON notation used for CBOR diagnostics, the payload 
containing a number of elements with key values should look like a JSON 
object with the structure list-name: {key: value}. Both key and value 
are composed of JSON objects separated by commas. For example consider 
the following YANG list specification:
module foo {
     namespace http://example.com/book;
     prefix “fo”;
     revision  2015-06-07;

    list B {
       key “key1 key2”;
       leaf key1 {type string;}
       leaf key2 {type string;}
       leaf coll {type int32;}
       leaf counter {type int32;}
    }
}

Consider the transport of two instances specified by <“key1” = “book1”, 
“key2” = “author2”> and by <“key1” = “book5”, “key2” = “author3”> out of 
a larger set of instances. The representation is different from the 
yang-json one for the reasons explained above.

The payload will look like:
{"B" :{
     {"key1" : "book1", "key2" : "author2"} :
     {"coll" : 500, "counter": 66} ,
     {"key1" : "book5", "key2" : "author3"} :
     {"coll" : 444, "counter": 11}
     }
}


Which translated to CBOR yields:

a1                         # map(1)
    61                      # text(1)
       42                   # "B"
    a2                      # map(2)
       a2                   # map(2)
          64                # text(4)
             6b657931       # "key1"
          65                # text(5)
             626f6f6b31     # "book1"
          64                # text(4)
             6b657932       # "key2"
          67                # text(7)
             617574686f7232 # "author2"
       a2                   # map(2)
          64                # text(4)
             636f6c6c       # "coll"
          19 01f4           # unsigned(500)
          67                # text(7)
             636f756e746572 # "counter"
          18 42             # unsigned(66)
       a2                   # map(2)
          64                # text(4)
             6b657931       # "key1"
          65                # text(5)
             626f6f6b35     # "book5"
          64                # text(4)
             6b657932       # "key2"
          67                # text(7)
             617574686f7233 # "author3"
       a2                   # map(2)
          64                # text(4)
             636f6c6c       # "coll"
          19 01bc           # unsigned(444)
          67                # text(7)
             636f756e746572 # "counter"
          0b                # unsigned(11)

The corresponding yang-json draft encoding - that allows transport of a 
selection of instances- does not specify the key fields and would have 
looked like:

{"B" : [
     {"key1" : "book1",
       "key2" : "author2”,
        "coll" : 500,
        "counter": 66
      } ,
     {"key1" : "book5",
       "key2" : "author3",
       "coll" : 444,
       "counter": 11,
     }
   ]
}

Suppose there are no key elements specified. In that case it is 
impossible to specify the wanted list elements, and always the whole 
list must be transported. In the case of a list without key 
specification is is best to use major type 4 composed of major type 5 to 
transport the list, as is specified in yang-json draft.

Consider the following YANG list

Module foo{
     Namespace http://example.com/book;
     Prefix “bo”
     Revision  2015-06-7
List B {
    Leaf title {type string;}
    Leaf author {type string;}
    Leaf coll {type int32}
    Leaf counter {type int32}
    }
}

Suppose the list contains two elements. The transport payload of the two 
elements looks like:

{"B" :[
     {"title" : "book1", "author" : "author2", "coll" : 500, "counter": 
66} ,
     {"title" : "book5", "author" : "author3",  “coll" : 444, "counter": 
11}
     ]
}

This payload is identical to the yang-json payload.
Which yields the corresponding CBOR code.

a1                         # map(1)
    61                      # text(1)
       42                   # "B"
    82                      # array(2)
       a4                   # map(4)
          65                # text(5)
             7469746c65     # "title"
          65                # text(5)
             626f6f6b31     # "book1"
          66                # text(6)
             617574686f72   # "author"
          67                # text(7)
             617574686f7232 # "author2"
          64                # text(4)
             636f6c6c       # "coll"
          19 01f4           # unsigned(500)
          67                # text(7)
             636f756e746572 # "counter"
          18 42             # unsigned(66)
       a4                   # map(4)
          65                # text(5)
             7469746c65     # "title"
          65                # text(5)
             626f6f6b35     # "book5"
          66                # text(6)
             617574686f72   # "author"
          67                # text(7)
             617574686f7233 # "author3"
          64                # text(4)
             636f6c6c       # "coll"
          19 01bc           # unsigned(444)
          67                # text(7)
             636f756e746572 # "counter"
          0b                # unsigned(11)


-- 
Peter van der Stok
vanderstok consultancy
mailto: [e-mail]