Re: [core] Comments on draft-ietf-core-yang-cbor-00

[Michel Veillette <[e-mail]>]

Hi Andy and thanks for your comments.
See [MV] bellow for my answers.

I'll wait for your reply before applying any changes to the latest draft.
http://core-wg.github.io/yang-cbor/draft-ietf-core-yang-cbor-latest.html

Regards,
Michel

From: core [mailto:[e-mail]] On Behalf Of Andy Bierman
Sent: May-16-16 7:13 PM
To: Core <[e-mail]>
Subject: [core] Comments on draft-ietf-core-yang-cbor-00

Hi,

Here are my comments on the YANG to CBOR draft


Andy


-------------------------------------------

sec. 3: para 4:

   The end user of this mapping specification
   can mandate the use of a specific key type or a specific subset of
   key types.

C1)  How does the end-user do this?

[MV]
The "end user" in this context is typically a specification.
For example, draft-veillette-core-cool-01 mandate SID as key type.

We should probably use something else than "end user"
Can you propose a new text to clarify the intent of this sentence?

-----------------------------------------

4.2.  The "container" Schema Node

   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).  A map is comprised of
   pairs of data items, with each data item consisting of a key and a
   value.

C2) Add a comment that "key" refers to the child node identifier
and value refers the the value of the child node. It does not
refer to the YANG term "key".

[MV] I proposing to add the following text. Fell free to propose an alternate text.

"Each key within the CBOR map is set to a data node identifier, each
value is set to the value of this data node instance."


----------------------------------------
sec 4.2:

   *SIDs as keys*

   Keys implemented using SIDs MUST be encoded using a CBOR unsigned
   integer (major type 0)

  2nd bullet:
    Delta values may result in a negative number, clients and servers
      MUST support negative deltas.


C3) Doesn't 2nd bullet require CBOR type 1?

Summary: KEY ENCODING (3 variants):
   SID:     Major type 0 or 1
   string:  Major type 3
   hash:    Major type 2

[MV] This issue is already fixed in the latest draft, see
http://core-wg.github.io/yang-cbor/draft-ietf-core-yang-cbor-latest.html#rfc.section.4.2

--------------------------------------------

5.3.  The "decimal64" Type

   Leafs of type decimal64 MUST be encoded using either CBOR unsigned
   integer (major type 0) or CBOR signed integer (major type 1),
   depending on the actual value.  The position of the decimal point is
   defined by the fraction-digits YANG statement and is not available in
   the CBOR encoding.

C4) How are decimal64 values that start with zero encoded?

   leaf foo {
     type decimal64 {
       fraction-digits 3;
     }
     default 0.005;
   }

[MV] If I use the default value as example, the value 0.005 is encoded as 0x05 in CBOR.
If a textual representation is required, the logic performing this conversion needs to add the leading zero(s) and the decimal point.

C5) You probably mean to convert the deciaml64 to a signed
or unsigned integer:

   1.005 == 1005

Then it is up to the decoder to know the YANG schema so it
can adjust based on the fraction-digits value.

[MV] Correct.

---------------------------------------------------

5.6.  The "enumeration" Type

   Leafs of type enumeration MUST be encoded using a CBOR unsigned
   integer data item (major type 0).

C6) Need to say that the implicit or explicit value-stmt value
is used, not the enumeration name like in XML or JSON

C7) Enumeration value is allowed to be negative, so major type 1 also
allowed

[MV]
Correct for both comments.
The first sentence need to be fixed and a clarification need to be added about the automatic assignment algorithm. I propose:

"Leafs of type enumeration MUST be encoded using a CBOR unsigned integer (major type 0) or CBOR signed integer (major type 1), depending on the actual value. Enumeration values are either explicitly assigned using the YANG statement "value" or automatically assigned based on the algorithm defined in [RFC6020biss] section 9.6.4.2.

------------------------------------------------------

5.7.  The "bits" Type

   Leafs of type bits MUST be encoded using a CBOR byte string data item
   (major type 2).

C8) Need to say that the implicit or explicit position-stmt value
is used, not the bit name like in XML or JSON

[MV]
Correct, I propose:

"Leafs of type bits MUST be encoded using a CBOR byte string data item (major type 2). The position of each bit is either explicitly assigned using the YANG statement "position" or automatically assigned based on the algorithm defined in [RFC6020biss] section 9.7.4.2."

------------------------------------------------------

5.8.  The "binary" Type

   Leafs of type binary MUST be encoded using a CBOR byte string data
   item (major type 2).

C9) What string format is used? base64? raw UTF-8?

[MV] No special format, just binary, see example.

------------------------------------------------------

5.12.  The "union" Type

   Leafs of type union MUST be encoded using the rules associated with
   one of the types listed.

C10) This does not really work because so many YANG types use
the same CBOR major encoding

   type union {
      type int32;
      type enumeration {
        enum A { value -5; }
        enum B { value 3; }
      }
      type bits {
        bit X { position 1; }
        bit Y { position 3; }
      }
      type decimal64 {
        fraction-digits 2;
      }
   }

How do I know if '3' is for int32, enum B or bit Y?
How do I know 103 is really decimal64 "1.03" and not
an int32 "103"?

[MV] Ouch, very good point.
I'm proposing to use CBOR tags for the following list of datatypes to avoid this kind of ambiguities.


·        bits

·        decimal64

·        enumeration

·        identityref

·        instance-identifier

·        leafref  (Only if if the datatype of the referenced leaf require a CBOR tag)

For the following list of  datatypes, they can be used directly without CBOR tag.


·        binary

·        boolean

·        empty

·        int8

·        int16

·        int32

·        int64

·        string

·        uint8

·        uint16

·        uint32

·        uint64

-------
Propose text:

Leafs of type union MUST be encoded using the rules associated with one of the types listed.
When use in a union, the following list of YANG datatypes are prefixed by CBOR tag to avoid confusion
between different YANG datatypes encoded using the same CBOR major type.

o bits
o decimal64
o enumeration
o identityref
o instance-identifier
o leafref  (Only if the datatype of the leaf referenced using the "path" YANG statement require a CBOR tag)

See section 7.1 for more information about CBOR tags.

-------
7.  IANA Considerations

7.1.  Tags Registry

This specification require the assignment of CBOR tags for the following YANG datatypes.
These tags are added to the Tags Registry as defined in section 7.2 of RFC 7049.

| Data Item | Semantics | Reference
| bits | YANG bits datatype | RFC6020biss, draft-ietf-core-yang-cbor
| decimal64 | YANG decimal64 datatype | RFC6020biss, draft-ietf-core-yang-cbor
| enumeration | YANG enumeration datatype | RFC6020biss, draft-ietf-core-yang-cbor
|  identityref | YANG identityref datatype | RFC6020biss, draft-ietf-core-yang-cbor
| instance-identifier | YANG instance-identifier datatype | RFC6020biss, draft-ietf-core-yang-cbor
|  leafref  | YANG leafref  datatype | RFC6020biss, draft-ietf-core-yang-cbor


C11)  Need to specify that types are evaluated in YANG
statement order (e.g., check int32, then enumeration, then bits)

[MV] I don’t understand this comment or proposed solution.

--------------------------------------------------------

sec. 5.13, para 5

   When SIDs identify a YANG list, the presence of the key(s) for this
   list is optional.  When the key(s) are present, the targeted instance
   within this list is selected.  When the key(s) are absent, the entire
   YANG list is selected.

C12) A YANG instance-identifier MUST identify exactly 1 instance.
It cannot specify all instances of a YANG list.

[MV] The definition of a list in RFC 6020 seem effectively to back-up this conclusion.

"list: An interior data node that may exist in multiple instances
in the data tree. A list has no value, but rather a set of child nodes."

Are you aware of any other places where this limitation is described?

If this is the case, the following sentences need to be removed and re-introduced as extension within
draft-veillette-core-cool when instance-identifiers are used in the context of the FETCH or iPATCH methods.


"When SIDs identify a YANG list, the presence of the key(s) for this list is optional.

When the key(s) are present, the targeted instance within this list is selected.

When the key(s) are absent, the entire YANG list is selected."

Note:
draft-veillette-core-cool already add two extensions to instance-identifier in the context of a FETCH or iPATCH,
we will need to add a third one. I still believe that using instance-identifier as the base construct
for FETCH and iPATCH make sense in order to minimize implementation footprint even if extensions are needed.

C13) If instance-identifier used in a union, no way to tell that
SID, name, or hash encoding is really an instance-identifier
and not a string or a number.

[MV] Addressed by my previous answer.

C14) How are the keys specified?  The CoMI draft specifies a URI encoding
but nothing in CBOR. Seems like they would have to be a separate string
(keys=A,14,fred).  Examples (e.g. for SID) using an array are not clear.

[MV] When key(s) are needed to qualify the instance-identifier, a CBOR array is used instead of a simple CBOR unsigned integer.
The first entry within the CBOR array is the SID, the next entries are the key(s) encoded using the rules defined for their datatypes.
There is no text conversion require to minimise the implementation footprint.

The following example:
"/ietf-system:system/authentication/user[name='bob']/authorized-key[name='admin']/key-data"

Is encoded as follow in CBOR:
[1721, "bob", "admin"]

Can you propose extra text which will clarify this item?

-----------------------------------------------------------

Attributes:

C15) XML and YANG/JSON allow meta-data to be sent with
the YANG data.  (e.g. NETCONF "operation" or "default" attributes)
How would meta-data be encoded in CBOR?

[MV] Can you provide me some reference to this topic.
I didn't find any references to "operation" and "default" in "draft-ietf-netmod-yang-json"

-----------------------------------------------------------

YANG List Keys:

C16) XML and YANG/JSON require YANG list keys to be encoded first
even if they are not defined first in the list.  This allows server
code to dispatch or do entry lookup without requiring buffering.
Should CBOR encoding of YANG lists require the same?

[MV] This is not possible for both JSON and CBOR.
The ordering of items within JSON objects or CBOR maps are arbitrary.

This is addressed in "draft-ietf-netmod-yang-json" section 5.4

"Unlike the XML encoding, where list keys are required to precede any
other siblings within a list entry, and appear in the order specified
by the data model, the order of members in a JSON-encoded list entry
is arbitrary because JSON objects are fundamentally unordered
collections of members. "