Subject: Re: [netmod] WG Last Call for draft-ietf-netmod-yang-metadata-01 (until 2015-06-29)

From: Kent Watsen <[email-masked]>
Date: Mon, 29 Jun 2015 13:13:31 +0000

All,

Today is the cutoff date for the Last Call for this draft, but the author indicated that comments received today or tomorrow can be incorporated into the draft-update being worked on.  So, if you have any lingering reviews, please send them before as soon as possible.

Thanks!
Kent

From: Kent Watsen <[email-masked]<mailto:[email-masked]>>
Date: Monday, June 15, 2015 at 6:49 PM
To: "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: [netmod] WG Last Call for draft-ietf-netmod-yang-metadata-01 (until 2015-06-29)

This is a notice to start a NETMOD WG last call for the document "Defining and Using Metadata with YANG":

https://tools.ietf.org/html/draft-ietf-netmod-yang-metadata-01

Please indicate your support by Monday June 29, 2015 at 9PM EST.
We are not only interested in receiving defect reports, we are equally
interested in statements of the form:

  "I have reviewed I-D XYZ and I found no issues"
  "I have implemented the data model in I-D XYZ"
  "I am implementing the data model in I-D XYZ"
  "I am considering to implement the data model in I-D XYZ"

This is the first Last Call for this document.

Kent, as NETMOD co-chair

---

From: "Alexander Clemm (alex)" <[email-masked]>
Date: Mon, 29 Jun 2015 15:27:38 +0000

Hi Lada,

FWIW, I have a few general question/comment on the draft, for which it might be useful to add clarification:

-          The general approach appears to be that metadata generally needs to be defined as part of the module, and when it is, must be supported.  How about augmenting an existing model with metadata "after" the fact (i.e. after the original definition)?  This appears to be potentially a more common usage in practice.  It would be useful to comment on expected usage, and perhaps add an example in which an existing model is augmented with metadata (or at least allude to the fact that this is a possibility).

-          How does metadata show up in regular operations - how is it modified and retrieved; how is it being populated?  I think it would also be helpful to add a section that illustrates usage of metadata. I was surprised to e.g. not see "default" as a substatement; is this something that should be added?

--- Alex

From: netmod [mailto:[email-masked]] On Behalf Of Kent Watsen
Sent: Monday, June 29, 2015 6:14 AM
To: [email-masked]
Subject: Re: [netmod] WG Last Call for draft-ietf-netmod-yang-metadata-01 (until 2015-06-29)

All,

Thanks!
Kent

Kent, as NETMOD co-chair

---

From: Benoit Claise <[email-masked]>
Date: Tue, 30 Jun 2015 01:14:42 +0200

Dear all,

As a contributor, I browsed through draft-ietf-netmod-yang-metadata

-
        The set of annotations must be extensible in a distributed manner
        so as to allow for defining new annotations without running into
        the risk of collisions with annotations defined and used by
        others.

What does "in a distributed manner" mean?

- In the introduction, you mention:
    Typical use cases are:

    o  Deactivating a subtree in a configuration datastore while keeping
       the data in place.

    o  Complementing data model information with instance-specific data.

    o  RPC operations may use metadata annotations for various purposes
       in both requests and responses.  For example, the <edit-config>
       operation in the NETCONF protocol (seesection 7.2 of [RFC6241] <https://tools.ietf.org/html/rfc6241#section-7.2>)
       uses annotations in the form of XML attributes for identifying the
       point in the configuration and type of the operation.

Don't you have any other examples than those 3?
What about showing these examples with the spec. in this document?
Note: I see that the first one is documented with module example-inactive

- Please correct the IANA considerations as in RFC7277, in particular the Registrant Contact:
    This document registers a URI in the "IETF XML Registry" [RFC3688 <https://tools.ietf.org/html/rfc3688>].
    Following the format inRFC 3688 <https://tools.ietf.org/html/rfc3688>, the following registration has been
    made.

        URI: urn:ietf:params:xml:ns:yang:ietf-ip

        Registrant Contact: The NETMOD WG of the IETF.

        XML: N/A; the requested URI is an XML namespace.

Regards, Benoit
>
> All,
>
> Today is the cutoff date for the Last Call for this draft, but the 
> author indicated that comments received today or tomorrow can be 
> incorporated into the draft-update being worked on.  So, if you have 
> any lingering reviews, please send them before as soon as possible.
>
> Thanks!
> Kent
>
>
>
> From: Kent Watsen <[email-masked] <mailto:[email-masked]>>
> To: "[email-masked] <mailto:[email-masked]>" <[email-masked] 
> <mailto:[email-masked]>>
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 30 Jun 2015 10:08:07 +0200

Hi Alex,

"Alexander Clemm (alex)" <[email-masked]> writes:

> -          The general approach appears to be that metadata generally
> needs to be defined as part of the module, and when it is, must be
> supported.  How about augmenting an existing model with metadata

Unfortunately, no. Annotations are defined via YANG extensions that may
be certainly ignored by the client, and perhaps even by the server - see my
earlier mail

https://mailarchive.ietf.org/arch/msg/netmod/TyObJv62iwRvfXgb1Lm-YGIwfP4

It would help somewhat to have "annotation" as a built-in statement
though not completely.

> "after" the fact (i.e. after the original definition)?  This appears
> to be potentially a more common usage in practice.  It would be useful
> to comment on expected usage, and perhaps add an example in which an
> existing model is augmented with metadata (or at least allude to the
> fact that this is a possibility).

Annotations are orthogonal to the "normal" YANG stuff. If they are
defined, and their use negotiated between the server and client, then
they can be used anywhere. In practice, an annotation may be designed,
e.g., for certain type(s) of data nodes, but from the YANG point of view
they aren't a new data node type, as attributes in XML. That's why
annotations are always defined at the top level of a module.

So, by design, annotations are not intended to augment a specific target
node.

>
> -          How does metadata show up in regular operations - how is it
> modified and retrieved; how is it being populated?  I think it would

The server or client can simply add them to NETCONF or RESTCONF payload,
using the encoding specified in the draft.

> also be helpful to add a section that illustrates usage of metadata. I
> was surprised to e.g. not see "default" as a substatement; is this
> something that should be added?

Given that annotations are not defined for specific locations in the
schema, defaults are not needed.

Lada

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 30 Jun 2015 10:35:20 +0200

Hi Benoit,

> As a contributor, I browsed through draft-ietf-netmod-yang-metadata

Thanks.

>ay

It means that different parties needn't coordinate the names and use of
annotations, as long as they don't choose conflicting YANG module names
or namespace URIs.

> Note: I see that the first one is documented with module

Well, the backlash I received with
draft-lhotka-netmod-yang-annotations-00 (expired) show that whilst there
is consensus about general utility of annotations, practical definitions
may be controversial. I could add the annotations from the above draft
as examples here but I fear they could still make for unnecessary
discussions.

Martin already pointed out in his review that it may be wiser to replace
the "inactive" annotation with something less controversial.

>         XML: N/A; the requested URI is an XML namespace.

OK, will do.

Thanks, Lada

---

From: Kent Watsen <[email-masked]>
Date: Tue, 30 Jun 2015 20:51:21 +0000

[As an individual contributor]

Already many comments have been made, hopefully he below comments are new:

1. In Section 3, it says:

  "By advertising a YANG module in which metadata annotation A is
   defined using the "md:annotation" statement, a server specifies
   support for the syntax of annotation A.  This means that
   configuration or state data, RPC messages and notifications will be
   considered syntactically valid if annotation A is attached to any
   data node instance, provided that all rules stated in this document
   are observed."

  Does this mean that the annotation A can be used by *any* module
  the server advertises, or just the modules that define/import
  annotation A?
 
  For example, could a YANG module be defined like this:

   module example-color-text {
     namespace "http://example.org/example-color-text";
     prefix "rgb";
     import ietf-yang-metadata { prefix "md"; }
     description
       "Text is black, unless colored otherwise";
     md:annotation color {
       type enumeration {
         enum red;
         enum green;
         enum blue;
       }
       description
         "This annotation only makes sense within this module.
          Application of this annotation to any data node
          Recursively applies to all its descendent nodes.";
     }
     container document {
       list paragraph {
         list sentence {
           leaf-list word {
             type string;
           }
         }
       }
     }
   }

  I assume that the intent is for the annotation to apply to
  the server as a whole, not any specific module.  It might
  help enforce this if annotations can only be defined in
  modules that don't define any data-nodes and it is required
  that the server advertises this module explicitly (not via
  an import)...

2. Also in Section 3, s/conditional:/conditional;/

3. In Section 4.2.2, adding metadata to the first entry in a list doesn't
seem elegant.  Can we instead create a special list element like the
following?

   "seq": [
     {
       "@": {
           "example-inactive:inactive": true

       }
     },
     {
       "name": "two",
       ...
     }
   ]

  I don't think that '@' is a valid identifier string, so it's
  syntactically OK, right?

4. Also in Section 4.2.2, an anydata example would complete this section...

5. In Section 4.2.3, an anyxml example would complete this section...

Thanks,
Kent