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

[Andy Bierman <[e-mail]>]

Hi Michel,

All of your proposed changes look good.
Re (C11): YANG 1.1 already specifies how the union type must be evaluated.
(In the order the member types are listed).
However, the results may not be the same for all encodings.

E.g,

   type union {
      type string;
      type int32;
   }

In XML, the element <foo>42</foo> would match the first type 'string'.
In JSON or CBOR, the encoding will specify string vs. integer, so
the positive integer 42 would not match type 'string'.

  { "foo": 42 }
  { "foo": "42" }


This is a problem for internal instrumentation that wants to be
encoding-independent,
but I do not know what to do about it.  We could force a type conversion
like XPath,
but this seems broken.

You should always design a YANG union so the pickiest types are listed
first,
always make string last.


On Tue, May 17, 2016 at 11:00 AM, Michel Veillette <
[e-mail]> wrote:

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


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