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

From: Kent Watsen <[email-masked]>
Date: Mon, 15 Jun 2015 22:49:32 +0000

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: Ladislav Lhotka <[email-masked]>
Date: Tue, 16 Jun 2015 13:50:50 +0200

>   "I have implemented the data model in I-D XYZ"

I have implemented support for metadata according to this document in
pyang, namely:

- DSDL validation takes properly defined metadata annotations into
  account,

- XML->JSON and JSON->XML translations properly convert metadata
  annotations.

Lada

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

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

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Jun 2015 09:54:39 +0200 (CEST)

Hi,

I have reviewed this document, and here are my comments.  I have some
technical issues; apart from that I think this document is ready
for publication.

I have also implemented this statement in pyang (see the branch
'yang-metadata' in pyang's github).

Technical issues:

  o  The 'type' statement is optional in 'md:annotation', and if it is
     not present, the type defaults to string.  I think this is bad
     design:
         
       - it is not consistent with how 'type' is used in other
         YANG statements (leaf, leaf-list, typedef).

       - it is not as clear for the reader as having an explicit
         type.

       - it saves just a few characters in every annotation (and
         annotations will be rare) so it is not worth it.

     I suggest making 'type' mandatory in 'md:annotation'.

  o  The type of the argument to 'md:annotation' is not specified.  It
     should be an "identifier" (as defined in 6020bis).

  o  Last paragraph of section 3 and the "description" in the
     extension.

     The text says that semantics are defined "by other means".  I
     think the semantics should be defined in the
     description/reference statements (by using links or inline text
     doesn't matter).

Editorial issues:

  o  You may want to change the "inactive" example to something less
     controversial.  For example:

     module example-comment {
       namespace "http://example.org/example-comment";
       prefix "ein";
       import ietf-yang-metadata {
         prefix "md";
       }
       md:annotation comment {
         type string;
         description
           "This annotation is used to attach a free-form comment to
            any data node.";
       }
     }

  o  Update the copyright year to 2015.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 17 Jun 2015 11:14:28 +0200

Hi Martin,

thanks for the review.

>      not present, the type defaults to string.  I think this is bad

I followed the example of RELAX NG where type of attributes needn't be
specified - as opposed to elements.

>      I suggest making 'type' mandatory in 'md:annotation'.

OK, I am not against making it mandatory, if it is the consensus.

>      should be an "identifier" (as defined in 6020bis).

Yes, I will add it to the description of the "extension" statement.

>      description/reference statements (by using links or inline text

Kent argued that an extension definition in YANG cannot make an
annotation part of the contract between the server and client: the
client can ignore it, and so the fact that the extension is defined in a
module advertised by the server isn't sufficient for the server to start
using the annotation and expect the client to take it into
account. Hence "by other means", which can be, e.g. a capability.

>      controversial.  For example:

Yes, I've also realized this. I just thought it might be good to show an
example with a non-string type and haven't got a better idea yet.

>   o  Update the copyright year to 2015.

OK.

Thanks, Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Jun 2015 12:12:16 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> account.

Agreed.

> Hence "by other means", which can be, e.g. a capability.

Take the inactive thing as an example.  I would assume that by
advertising the module where inactive is advertised, the server
announces that it implements the syntax *and semantics* of this new
annotation.  I do not expect one capability for the syntax, and
another for the semantics.

(I also note that your requirement lists:

   2.  Syntax and semantics of annotations must be documented and the
       documentation must be easily accessible.
)

But I also don't want this document to go into all details of how
different annotations can be used; this needs to be carefully designed
for each annotation.  

I suggest something like this:

OLD:

   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.

   However, the semantics of an annotation, usage rules, and expected
   behavior of clients and servers MUST be specified separately by other
   means that are outside the scope of this document.

NEW:

   By advertising a YANG module in which metadata annotation A is
   defined using the "md:annotation" statement, a server specifies
   support for the syntax and semantics 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.

and

OLD:

          A server announces syntactic support for a particular
          annotation by including the module in which the annotation is
          defined among the advertised YANG modules (e.g., in NETCONF
          hello message).

          Semantics and usage rules for an annotation MUST be specified
          separately. The 'description' and/or 'reference' statements
          SHOULD provide corresponding links.

NEW:

          A server announces support for a particular
          annotation by including the module in which the annotation is
          defined among the advertised YANG modules (e.g., in NETCONF
          hello message).

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 17 Jun 2015 13:41:56 +0200

> On 17 Jun 2015, at 12:12, Martin Bjorklund <[email-masked]> wrote:
> 

Well, but it is exactly what Kent objected against. It is the requirement to support “old clients” that causes the trouble here (and elsewhere). If client A sets “inactive” somewhere, then the datastore semantics will change also for client B that doesn’t understand “inactive” and may be wondering why the server ignores his edits.

I understand (although RFC 6241 doesn’t say it explicitly) that, unlike YANG extensions, a NETCONF capability advertised by the server can be mandatory for the client in the sense that it has to understand and honour it.

A conclusion of this may be that it makes no sense to define annotations through YANG extension after all. On the other hand, I do see a value of having annotations defined in YANG modules.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 17 Jun 2015 13:51:09 +0200

> I understand (although RFC 6241 doesn’t say it explicitly) that, unlike YANG extensions, a NETCONF capability advertised by the server can be mandatory for the client in the sense that it has to un…

There is no way for a client to tell whether a certain capability URI
(it has never seen before) is mandatory to understand or not. In fact,
I would say in a proper solution it would be the server would have to
close the connection if it finds a client that does not understand its
language. And yes, we are on very slippery grounds here. If
implementors can create arbitrary cool 'annotations' that break
clients that do not understand them, we will loose interoperability.

> A conclusion of this may be that it makes no sense to define
> annotations through YANG extension after all. On the other hand, I
> do see a value of having annotations defined in YANG modules.

Without further protocol support to negotiate annotations, I think
annotations must be limited to things that can be safely ignored by a
client. I have not read the I-D yet but I would expect that it should
say something like that. ;-)

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Jun 2015 14:20:01 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> Well, but it is exactly what Kent objected against. It is the
> requirement to support “old clients” that causes the trouble here (and
> elsewhere). If client A sets “inactive” somewhere, then the datastore
> semantics will change also for client B that doesn’t understand
> “inactive” and may be wondering why the server ignores his edits.

Absolutely!

> I understand (although RFC 6241 doesn’t say it explicitly) that,
> unlike YANG extensions, a NETCONF capability advertised by the server
> can be mandatory for the client in the sense that it has to understand
> and honour it.

No!

My point is that how this affects the client must be considered
case-by-case.

In our implementation we support inactive, but the server sends the
attribute only if the client explcitly asks for it
(<with-inactive>true</with-inactive>, similar to with-default).

> annotations through YANG extension after all.

No I think this is the right way to do it.

/martin

> On the other hand, I do
> see a value of having annotations defined in YANG modules.
> 
> Lada
> 
> 
> >

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 17 Jun 2015 14:34:52 +0200

> On 17 Jun 2015, at 13:51, Juergen Schoenwaelder <[email-masked]> wrote:
> 

So it means that, e.g. the annotations from

https://tools.ietf.org/html/draft-kwatsen-conditional-enablement-00

cannot be safely used by the server even after advertising them via :conditional-enablement capability. 

> say something like that. ;-)

But it’s not a specific problem of this draft, it would simply mean that annotations that cannot be ignored cannot be used at all, no matter what. However, some annotations that have been proposed (and probably used in the wild) are of that sort.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 17 Jun 2015 14:43:00 +0200

> On 17 Jun 2015, at 14:20, Martin Bjorklund <[email-masked]> wrote:
> 

But it’s not only matter of whether the server sends the attribute or not but rather whether the server applies the inactive parts, and this decision must be the same for all clients.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Jun 2015 14:46:45 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> But it’s not only matter of whether the server sends the attribute or
> not but rather whether the server applies the inactive parts, and this
> decision must be the same for all clients.

Again, my point is really that what to do and what is a safe behavior
depends on the attribute.  This document should not try to solve that
problem.

(In our case, if the client doesn't ask for inactive nodes, we prune
them from the result).

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 17 Jun 2015 14:50:11 +0200

> cannot be safely used by the server even after advertising them via :conditional-enablement capability.

Yes, advertisement is not sufficient.

> But it’s not a specific problem of this draft, it would simply mean that annotations that cannot be ignored cannot be used at all, no matter what. However, some annotations that have been proposed…

They cannot be used safely until there is an annotation negotiation
mechanism, or as Martin indicated, a way for a client to explicitely
enable the functionality associated with certain annotations.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 17 Jun 2015 15:13:48 +0200

> On 17 Jun 2015, at 14:50, Juergen Schoenwaelder <[email-masked]> wrote:
> 

Even this breaks down if an annotation has global side effects. This actually seems to be true for the whole idea of a client cherry-picking from the capabilities (and YANG modules) advertised by the server.

Lada

---

From: Andy Bierman <[email-masked]>
Date: Wed, 17 Jun 2015 08:13:30 -0700

On Wed, Jun 17, 2015 at 6:13 AM, Ladislav Lhotka <[email-masked]> wrote:

>
> > On 17 Jun 2015, at 14:50, Juergen Schoenwaelder <
> [email-masked]> wrote:
> >
> >>> On 17 Jun 2015, at 13:51, Juergen Schoenwaelder <
> [email-masked]> wrote:
> >>>
> semantics will change also for client B that doesn’t understand “inactive”
> and may be wondering why the server ignores his edits.
> >>>>
> unlike YANG extensions, a NETCONF capability advertised by the server can
> be mandatory for the client in the sense that it has to understand and
> honour it.
> >>>
> >> But it’s not a specific problem of this draft, it would simply mean
> that annotations that cannot be ignored cannot be used at all, no matter
> what. However, some annotations that have been proposed (and probably used
> in the wild) are of that sort.
> >>
> >
> Even this breaks down if an annotation has global side effects. This
> actually seems to be true for the whole idea of a client cherry-picking
> from the capabilities (and YANG modules) advertised by the server.
>
>

IMO conditional enablement is trivial to add in a way that does not break
clients unaware of the disabled nodes.  As Martin pointed out, the only
way the client can see them is to ask explicitly that the metadata be
returned.
Otherwise the disabled nodes look like deleted nodes.  For validation
purposes, they are deleted nodes.

The NETCONF-EX <get2> operation had a "metadata" parameter so the
client could ask for specific attributes.  Hard-wired parameters like
"with-defaults" or "with-disabled" will also work.

If the client cannot ignore the behavior defined by the capability,
then it isn't a NETCONF protocol capability, it's a different non-standard
protocol.

> Lada

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 17 Jun 2015 18:11:25 +0200

> On 17 Jun 2015, at 17:13, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> way the client can see them is to ask explicitly that the metadata be returned.

I don’t think it is that easy. What if an unaware client creates something in the inactive area which he sees as empty? Will all the inactive subtree be deleted?

But I agree this is not the time to discuss this particular annotation. Martin proposed some text changes and I’d like to know whether everybody is happy with them.

Lada

---

From: Kent Watsen <[email-masked]>
Date: Wed, 17 Jun 2015 17:25:32 +0000

>depends on the attribute.  This document should not try to solve that

This makes sense to me

>(In our case, if the client doesn't ask for inactive nodes, we prune

But then doesn't round-tripping (replace) cause the inactive nodes to be
lost?

Thanks,
Kent

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 26 Jun 2015 16:33:27 +0200

Hi,

I have reviewed draft-ietf-netmod-yang-metadata-01 and I have a couple
of comments.

- I would prefer if the terminology would be streamlined. Currently,
  the I-D sometimes uses "metadata", sometimes "annotation", sometimes
  "metadata annotation". If these terms all mean the same, then I
  suggest we settle on a single term. Furthermore, the YANG statement
  'annotation' is defined in the module 'ietf-metadata'. I am not sure
  whether there is a specific reasoning behind this.

- In order to group YANG modules together that define YANG extensions
  and nothing else, does it make sense to call them 'ietf-yang-<xxx>'?

- I am having problems with the examples presented in the
  Introduction.  The 'deactivating a subtree' annotation requires a
  negotiation mechanism to be robust. The usage of attributes in the
  <edit-config> is more a protocol specification detail. Do you
  suggest that annotations would be used to define them? If so, how?

  I think there needs to be text in section 1 that distinsuishes
  between annotations that are harmless (because they can be ignored)
  and annotations that require annotation negotiation in order to be
  used.

- Why is the type statement optional for annotations? This seems to be
  inconsistent with the YANG rules.

- The definition of 'inactive' on page 6 is kind of confusing. The
  text says the presence of the annotation deactives a data node.
  If so, why is the type of the annotation a boolean?

- The text about advertisements is not clear. I think a server
  advertising annotation A not only commits to comply to this I-D but
  also to the semantics of the annotations A. I note that there is no
  mechanism to scope annotations - a server either support annotations
  for all data models it implements or none. Is this correct?
  Furthermore, if a module M defines annotation A and it contains also
  other definitions, then I can't implement M without implementing A
  system wide? That is, it is advisable to define annotations in their
  own separate modules in order to preserve flexibility, no?

- Does the presence of an annotation impact the JSON encoding rules
  that control when a module name prefix is needed or not? I assume
  the answer is 'no' but it is not clear from the text.

- s/whose the/whose/

- bump the copyright year to 2015

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 29 Jun 2015 15:22:55 +0200

> I have reviewed draft-ietf-netmod-yang-metadata-01 and I have a couple

Thanks, my replies are inline.

>   whether there is a specific reasoning behind this.

In my interpretation, metadata is a more general term, i.e. metadata of an
instance document may consist of multiple (different) annotations.

That said, it should be possible to get rid of the "metadata" term, and
change the module name e.g. to "ietf-annotation-extension"

>   and nothing else, does it make sense to call them 'ietf-yang-<xxx>'?

Such a convention, if it is agreed upon, IMO belongs to 6087bis. Moreover, ietf-yang-types
doesn't fit this pattern. 

>   negotiation mechanism to be robust. The usage of attributes in the

Martin already proposed using a less controversial example in his review, and I agreed.

>   suggest that annotations would be used to define them? If so, how?

I haven't thought about this particular use, although it probably won't
be any worse than "get-filter-element-attributes" extension in the
"ietf-netconf" module. 

>   and annotations that require annotation negotiation in order to be

I am not sure there is a good and absolute definition of "harmless", it
depends on the context. For example, if DSDL mapping ignores the
extension, then no instance document containing *any* XML attributes (no
matter how benign) can ever be successfully validated with the generated
RELAX NG schema.

I agree it is a problem but IMO it comes down to the (wrong) assumption
that a client is free to cherry-pick arbitrary parts of the data model
advertised by the server, without even telling the server which parts were
chosen/omitted.

>   inconsistent with the YANG rules.

This was also in Martin's review, and I am ready to make it mandatory.

>   If so, why is the type of the annotation a boolean?

Yes, it should be "presence with the value of 'true'".

>   also to the semantics of the annotations A. I note that there is no

I'd agree with this but see below.

>   for all data models it implements or none. Is this correct?

Yes.

>   own separate modules in order to preserve flexibility, no?

Not sure, it depends on what this text in 6020(bis) really means:

   If a YANG compiler does not support a particular extension, which
   appears in a YANG module as an unknown-statement (see Section 13),
   the entire unknown-statement MAY be ignored by the compiler.

I would assume that servers also use a "YANG compiler", so the above
wording may also mean that the server can ignore extensions even in
modules it advertises.

>   the answer is 'no' but it is not clear from the text.

Bullet #1 in sec. 4.2 says this.

> - s/whose the/whose/

Corrected.

> - bump the copyright year to 2015

Yes, Martin already noticed this one, too.

Thanks, Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 30 Jun 2015 11:09:11 +0200

> instance document may consist of multiple (different) annotations.

This is one possible explanation. I am fine if this is spelled out
clearly so that readers understand how the words are used.

> doesn't fit this pattern. 

Yes, not an extension in the strict sense but still a rather standard
extension of basic types. I would find ietf-yang-* nice to list all
"basic" yang modules but then I am not religious about it either
(ietf-yang-annotation would be a concrete proposal).

> be any worse than "get-filter-element-attributes" extension in the

Again, I prefer to pick a less controversial example. One can of
course debate whether 'type' and 'select' (this is what
get-filter-element-attributes defines) are generic annotations.
I would not think so.

> advertised by the server, without even telling the server which parts were

I do not understand the last paragraph. Anyway, for me, the fact that
it is difficult to define "harmless" seems to underpin the need for
discussion. It is not even clear to me whether a generic NETCONF
client is required to preserve any attributes it receives. For
annotations that are purely maintained by the NC server (e.g. the
timestamp of the last modification), this is not an issue. For
anything that is client provided, this is not at all clear and if an
annotation changes server behaviour or the interpretation of the data,
this clearly requires some sort of agreement that both endpoints know
what they are doing.

> wording may also mean that the server can ignore extensions even in

If so, there needs to be a way to reliably obtain the information
which annotations are actually supported.
 
> Bullet #1 in sec. 4.2 says this.

I did not find the two bullets clear enough. The second bullet says:

   2.  Namespaces of metadata annotations are encoded in the same way as
       namespaces of YANG data node instances, see
       [I-D.ietf-netmod-yang-json].

This leaves it up for interpretation whether this means just the
syntax or whether this also refers to the rules when namespaces must
be included. The first bullet did not help me to understand this
either, hence I asked the question. I love to have more explicit text,
perhaps even an example (if I have two annotations 'a' and 'b' defined
in one module and another annotation 'c' defined in a second module
together with a leaf 'd', what are the possible namespace combinations
I will get if I reorder the annotations?).

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 30 Jun 2015 13:44:11 +0200

> clearly so that readers understand how the words are used.

OK, I will try to figure out what's better.

> (ietf-yang-annotation would be a concrete proposal).

Fine with me.

> get-filter-element-attributes defines) are generic annotations.

I'd love to hear about use cases and examples that are less
controversial but still not completely useless. Having none begs the
question of why annotations are needed at all.

> I do not understand the last paragraph. Anyway, for me, the fact that

The last paragraph means that there should be a mechanism for *both*
server and client to tell the other side the exact data model it is
using. The idea that a client (old or whatever) just silently picks a
subset of the server's model is IMO terribly broken.

Yes.

> which annotations are actually supported.

Absolutely, although it might suffice to clarify the "YANG compiler" thing.

> be included. The first bullet did not help me to understand this

For annotations in JSON, the namespace ID (module name) must always be
included in their name, and annotations are essentially leaves so they
cannot participate in any "namespace switching". And bullet #1 says
encoding of other nodes is unaffected by the presence of annotations.

> I will get if I reorder the annotations?).

I don't understand. Do you mean reordering within a single "metadata object"?
The order of its members is irrelevant, and all members must have an
explicit namespace.

With a data model consisting of these two modules,

module foo {
  ...
  md:annotation a;
  md:annotation b;
}

module bar {
  ...
  md:annotation c;
  leaf d { type uint8; }
}

the correct JSON encoding is

{
  "bar:d": 42,
  "@bar:d": {
    "foo:a": "xxx",
    "foo:b": "yyy",
    "bar:c": "zzz"
  }
}

modulo member reordering, but the namespaces need to be as shown.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 30 Jun 2015 14:12:15 +0200

OK.

/js