Subject: Re: [core] COOL SID representation

From: Michel Veillette <[email-masked]>
Date: Fri, 1 Apr 2016 14:03:49 +0000

Hi Peter

I like your suggestion to show delta SIDs in the CBOR diagnostic notation using the "+" sign.
This syntax is supported by the CBOR diagnostic notation and tools like http://cbor.me/

I did the modification in our working document, see:
https://core-wg.github.io/yang-cbor/draft-veillette-core-yang-cbor-mapping-latest.html#container
https://core-wg.github.io/yang-cbor/draft-veillette-core-yang-cbor-mapping-latest.html#list

For example:
{
  1708 : {                              # clock
    +2 : "2015-10-02T14:47:24Z-05:00",  # current-datetime, SID 1710
    +1 : "2015-09-15T09:12:58Z-05:00"   # boot-datetime, SID 1709
  }
}

About PUT and PATCH methods in CoOL, it's important to understand that the payload contain a list of data nodes encoded using a CBOR array.
This list implements previous sibling delta SID (instead of the parent delta SID implemented in containers and list instances).
This list is defined in the intro of section 5.3 and 5.4:
(https://core-wg.github.io/yang-cbor/draft-veillette-core-cool-latest.html#put-updating-all-data-nodes-of-a-datastore)

   The payload of the PUT request MUST carry a CBOR array containing the new content of the datastore.
   The CBOR array MUST contain a list of pairs of delta and associated value. A delta represents the
   different between the current SID and the SID of the previous pair within the CBOR array. Each
   value is encoded using the rules defined by [I-D.veillette-core-yang-cbor-mapping].

About the example you are referencing, the +15 is a previous sibling delta SID within the CBOR array. (Top level list of data node)
The value +3 for example is a parent delta SID within the CBOR map (YANG container)
I understand that this encoding is confusing for peoples but not very complex for a computer.
The alternate methods proposed to be as concise (such the Order Preserved Multi-Maps - OPMM) was a lot more complex. 

https://core-wg.github.io/yang-cbor/draft-veillette-core-cool-latest.html#put-updating-all-data-nodes-of-a-datastore

PUT /c/r Content-Format(application/cool+cbor)
[
  1727, 540,                     # timezone-utc-offset (SID 1727)
  +15, true,                     # enabled (SID 1742)
  +1, [                          # server (SID 1743)
    {
      +3 : "tic.nrc.ca",         # name (SID 1746)
      +4 : true,                 # prefer (SID 1747)
      +5 : {                     # udp (SID 1748)
        +6 : "132.246.11.231",   # address (SID 1749)
        +7 : 123                 # port (SID 1750)
      }
    },
    {
      +3 : "tac.nrc.ca",         # name (SID 1746)
      +4 : false,                # prefer (SID 1747)
      +5 : {                     # udp (SID 1748)
        +6 : "132.246.11.232"    # address (SID 1749)
      }
    }
  ] 
]

Regards,
Michel

-----Original Message-----
From: core [mailto:[email-masked]] On Behalf Of peter van der Stok
Sent: March-30-16 8:40 AM
To: Core <[email-masked]>
Subject: [core] COOL SID representation

Hi Michel et al,

I find the current representation of the SID rather confusing, both within the examples as the CBOR encoding.
The numeric values serving as YANG identifier are represented as differences with respect to a hierarchical higher value.
It would be more clear if the operator aspect was shown in the examples: 
e.g. +15 instead of 15.
  It is not clear to me why the operation is with respect to the parent schema node.
Could it not just be the former identifier? Efficiency considerations may then indicate a reordering of the nodes, but that is not prohibitive for the handling of the contents.

 From the above you may understand that I do not like misusing the "integer" type in CBOR to annotate Delta's.
It makes the interpretation of the CBOR types application dependent, and I don't think that is a good direction to go.
My recommendation is to develop a new CBOR element to denote the deltas.

Greetings, Peter

_______________________________________________
core mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/core

---

From: peter van der Stok <[email-masked]>
Date: Sat, 02 Apr 2016 19:00:38 +0200

> notation using the "+" sign.

Fine it helps me at least.
It would help as well if the annotation (may be not the CBOR contents) 
displays the parent value.

> [I-D.veillette-core-yang-cbor-mapping].

This confuses me, because the ordering is used (e.g A delta represents 
the different between the current SID and the SID of the previous pair
within the CBOR array);
So why in arrays yes to ordering, and elsewhere, no to ordering.
Especially as the client and server are both aware of the ordering in 
the payload; and the ordering will not change during transport.

So on one hand you have the SIDs of the items to transport.
On the other hand you transport them, and then you can encode them as 
you wish, also using the ordering as long as the generated SID values 
are correct.

Peter

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 02 Apr 2016 14:17:16 -0300

> This syntax is supported by the CBOR diagnostic notation and tools like http://cbor.me/

(Actually, strictly speaking, this is a bug in cbor.me: +1 is not
allowed in JSON, and the CBOR diagnostic notation as defined in section
6 of RFC 7049 does not explicitly extend JSON here.  But I think we can
just add the + sign to the number extensions defined for the extended
diagnostic notation in appendix G.4 of
draft-greevenbosch-appsawg-cbor-cddl, which is the one we want to use here.)

Grüße, Carsten

---

From: Michel Veillette <[email-masked]>
Date: Sat, 2 Apr 2016 19:52:07 +0000

Hi Peter

The constrains imposed by the CBOR map (ordering not preserved, no duplicate keys allowed) is not an issue during the transport, is something imposed by the libraries used on both side (to serialize and de-serialise).

For example, if you enter the following in http://cbor.me/

{
  2 : "a",
  2 : "b"
}

It will produce a cbor map with a single entry instead of two.

a1       # map(1)
   02    # unsigned(2)
   61    # text(1)
      62 # "b"

http://cbor.me/ preserve the ordering but other libraries written in python for example won't.

Hope this answer your question.

Michel

-----Original Message-----
From: peter van der Stok [mailto:[email-masked]] 
Sent: April-02-16 1:01 PM
To: Michel Veillette <[email-masked]>
Cc: [email-masked]; Core <[email-masked]>
Subject: RE: [core] COOL SID representation

Fine it helps me at least.
It would help as well if the annotation (may be not the CBOR contents) displays the parent value.

> [I-D.veillette-core-yang-cbor-mapping].

This confuses me, because the ordering is used (e.g A delta represents the different between the current SID and the SID of the previous pair within the CBOR array); So why in arrays yes to ordering, and elsewhere, no to ordering.
Especially as the client and server are both aware of the ordering in the payload; and the ordering will not change during transport.

So on one hand you have the SIDs of the items to transport.
On the other hand you transport them, and then you can encode them as you wish, also using the ordering as long as the generated SID values are correct.

Peter