Subject: [core] YANG to CBOR mapping

From: peter van der Stok <[email-masked]>
Date: Thu, 10 Mar 2016 10:06:32 +0100

Hi Michel,

I read through the provisional draft; and have a few high level remarks

It is nice to see that you follow the same structure as in 
netmod-yang-json.

The mapping from YANG name to string, I understand.
The mappings of the SID and the hash pose me problems.
The SID and and hash are both numbers, why not map them both to unsigned 
integer (major type 0)?
The server does not care how these numbers are produced, it only needs 
to map the number to the memory locations in the server.

I would also suggest that you add a section about mapping instances of 
lists.
When you want memory reduction, the sending of a single instance of a 
list instead of a whole list may result in the saving of tens of bytes 
if not much more.

Greetings,

peter

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 10 Mar 2016 10:31:56 +0100

Hi Peter,

> The SID and and hash are both numbers, why not map them both to unsigned

SIDs benefit from compression by delta encoding (turning them into
signed integers in the actual delta).
Delta encoding does not make sense for hashes (just spreads the numbers
further out).
So it is useful to be able to *distinguish* the two, specifically before
the delta encoding kicks in.

One way that came up for this in discussions about how to best use CBOR
for YANG data representation is to represent the hashes as binary
strings.  E.g., if the hash value is 1234567890, what might have been

1a 499602d2 # unsigned(1234567890)

becomes h'499602d2' or

44          # bytes(4)
   499602d2 # "I\x96\x02\xD2"

Since hashes are evenly distributed in the 30-bit space, there is no
change in the number of bytes needed (except maybe for the p = 1/16384
case that the hash happens to be < 65536).

With this way of distinguishing identifiers, in the end, we can have a
mapping of CBOR data types to identifiers:

CBOR type     meaning
integer       delta encoded SID
byte string   hash
text string   native YANG identifier

(It is then a matter of design and/or deployment which of these kinds of
identifiers are actually used in a specific instance.)

> to map the number to the memory locations in the server.

Exactly.

Grüße, Carsten

---

From: peter van der Stok <[email-masked]>
Date: Thu, 10 Mar 2016 10:52:40 +0100

Hi Carsten,

thanks, see below.

>    499602d2 # "I\x96\x02\xD2"
<pvds>
Is misinterpreted this in the draft as a rather long "character" string
thanks for the explanation
</pvds>
> text string   native YANG identifier
<pvds>
like the table
</pvds>

---

From: Michel Veillette <[email-masked]>
Date: Thu, 10 Mar 2016 15:07:46 +0000

Hi Peter

=== About the octet string

I agree that the use of byte string for the hash is slightly disturbing since all the previous works have been done with integers.
The rational is to use a different CBOR type for the three type of naming (string, octet string, integer).
A collateral advantage of using the octet string is that you can now uses the diagnostic notation with hexadecimal digits (e.g h'334c67d9') which is supported by [RFC7049] and tools like http://cbor.me/ .

=== About list instance

On the identification side of list instance, I thinks this is fully documented in section (https://core-wg.github.io/yang-cbor/draft-veillette-core-yang-cbor-mapping-latest.html#rfc.section.5.13) and the third example in this section address specifically this topic.

On the encoding side, we mention list instances in section (https://core-wg.github.io/yang-cbor/draft-veillette-core-yang-cbor-mapping-latest.html#rfc.section.4.2) 
"Collections such as containers, list instances, notifications, RPC inputs, RPC outputs, action inputs and action outputs MUST be encoded using a CBOR map data item (major type 5)."
However, we don't have a specific example.
This is the case also for notifications, RPC inputs, RPC outputs, action inputs and action outputs.
However, we have these examples in CoOL and in CoMI.

Is it sufficient?

Regards,
Michel

-----Original Message-----
From: peter van der Stok [mailto:[email-masked]] 
Sent: March-10-16 4:07 AM
To: Core <[email-masked]>; Michel Veillette <[email-masked]>
Subject: YANG to CBOR mapping

Hi Michel,

It is nice to see that you follow the same structure as in netmod-yang-json.

The mapping from YANG name to string, I understand.
The mappings of the SID and the hash pose me problems.
The SID and and hash are both numbers, why not map them both to unsigned integer (major type 0)?
The server does not care how these numbers are produced, it only needs to map the number to the memory locations in the server.

I would also suggest that you add a section about mapping instances of lists.
When you want memory reduction, the sending of a single instance of a list instead of a whole list may result in the saving of tens of bytes if not much more.

Greetings,

peter

---

From: peter van der Stok <[email-masked]>
Date: Mon, 14 Mar 2016 09:41:30 +0100

Hi Michel

I'm confused about the answers below.

> === About list instance
> 
> On the identification side of list instance, I thinks this is fully
> documented in section
> (https://core-wg.github.io/yang-cbor/draft-veillette-core-yang-cbor-mapping-latest.html#rfc.section.5.13)
> and the third example in this section address specifically this topic.

This section is about the "instance-identifier" not about the instance.

> 
> On the encoding side, we mention list instances in section
> (https://core-wg.github.io/yang-cbor/draft-veillette-core-yang-cbor-mapping-latest.html#rfc.section.4.2)
> "Collections such as containers, list instances, notifications, RPC
> inputs, RPC outputs, action inputs and action outputs MUST be encoded
> using a CBOR map data item (major type 5)."

This section is about lists without keys.

My suggestion is to create a section that describes the encoding of list 
instances (multiple instances) identified with key values.
I prefer to have that subject handled here, so it is not exclusively 
comi speak, but for example can be used also for restconf.

Greetings,

Peter

---

From: Michel Veillette <[email-masked]>
Date: Mon, 14 Mar 2016 15:42:51 +0000

Hi Peter

List instances are defined in section 7.8 of RFC 6020, I-D.ietf-netmod-rfc6020bis-09.
(https://tools.ietf.org/html/rfc6020#section-7.8.3.1) 

For example, the following definition:

list server {
  key "name";
  unique "ip port";
  leaf name {
    type string;
  }
  leaf ip {
    type inet:ip-address;
  }
  leaf port {
    type inet:port-number;
    }
}

Is encoded in xml as:

<server>
  <name>smtp</name>
  <ip>192.0.2.1</ip>
  <port>25</port>
</server>

In draft-ietf-netmod-yang-json, the encoding of a list instance in JSON is defined in section 5.4.
(https://tools.ietf.org/html/draft-ietf-netmod-yang-json-09#section-5.4) 
"A list instance is encoded as a name/array pair, and the array elements are JSON objects."

For the above example, the JSON encoding is:

{
  "name" : "smtp",
  "ip" : "192.0.2.1",
  "port" : 25
}

I-D.veillette-core-yang-cbor-mapping use the same approach in section 4.4 and propose a CBOR map.
(https://tools.ietf.org/html/draft-veillette-core-yang-cbor-mapping-00#section-4.4)

 For the above example, the CBOR encoding is:

* For name*

Diagnostic notation:
{
  "name" : "smtp",
  "ip" : "192.0.2.1",
  "port" : 25
}

CBOR encoding (31 bytes):
a3
   64
      6e616d65
   64  
      736d7470
   62
      6970 
   69
      3139322e302e322e31
   64
      706f7274
   18 19

* For YANG hashes*
Assuming:
- YANG hash of "/unknown-module:server/name" = h'0e99676c'
- YANG hash of "/unknown-module:server/ip" = h'2aa29479'
- YANG hash of "/unknown-module:server/port" = h'30f67b93'

Diagnostic notation:
{
  h'0e99676c' : "smtp",
  h'2aa29479' : "192.0.2.1",
  h'30f67b93' : 25
}

CBOR encoding (33 byte):
a3
   44 
      0e99676c
   64
      736d7470
   44
      2aa29479
   69
      3139322e302e322e31
   44
      30f67b93
   18 19

* For SID *
Assuming:
- SID of "/unknown-module:server/name" = 1576
- SID of "/unknown-module:server/ip" = 1577
- SID of "/unknown-module:server/port" = 1578

Diagnostic notation:
{
  1576 : "smtp",
  1577 : "192.0.2.1",
  1578 : 25
}

CBOR encoding (27 byte):
a3
   19 0628
   64
      736d7470
   19 0629
   69
      3139322e302e322e31
   19 062a
   18 19

* For SID delta *

Diagnostic notation:
{
  1 : "smtp",
  2 : "192.0.2.1",
  3 : 25
}

CBOR encoding (21 byte):
a3
   01
   64
      736d7470
   02
   69
      3139322e302e322e31
   03
   18 19

I understand that CoMI introduces a new approach to encode List instances
which add metadata to identify which data nodes are keys and which ones are
associated data. For the XML and JSON encoding, it seems too late to change
the way list instances are encoded. For the CBOR encoding, adding metadata
will be in contradiction with the "Properties of the CBOR Encoding" as defined
in section 3
(https://tools.ietf.org/html/draft-veillette-core-yang-cbor-mapping-00#section-3).

 "In order to minimize the size of the encoded data, the proposed
   mapping does not make use of any meta-information beyond those
   natively supported by CBOR."

If this assumption in not what you had in mind, please clarify.

Regards,
Michel

-----Original Message-----
From: peter van der Stok [mailto:[email-masked]] 
Sent: March-14-16 4:42 AM
To: Michel Veillette <[email-masked]>
Cc: [email-masked]; Core <[email-masked]>
Subject: RE: YANG to CBOR mapping

Hi Michel

My suggestion is to create a section that describes the encoding of list instances (multiple instances) identified with key values.
I prefer to have that subject handled here, so it is not exclusively comi speak, but for example can be used also for restconf.

Greetings,

Peter