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

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 01 Jul 2015 10:24:27 +0200

Hi Kent,

thanks for reviewing the document.

Kent Watsen <[email-masked]> writes:

> [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 all modules implemented by the server, no import is needed.

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

Yes. The description can also say that the annotation is ignored
elsewhere.

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

I expect this will be the normal way of defining annotations, and it
could appear in the document as a guideline. I don't think though it is
necessary to state it as a hard rule.

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

OK.

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

Maybe I don't understand but the idea is that a separate metadata objects
can be attached to any or all entries of a list. In the example it is
added only to the first entry but another metadata object could be added
to the second entry as well.

It is not possible to add an annotation to the whole list, also because
this cannot be represented in XML encoding (via attributes).

>
>    "seq": [
>      {
>        "@": {
>            "example-inactive:inactive": true
>
>        }
>      },
>      {
>        "name": "two",
>        ...
>      }
>    ]
>
>   I don't think that '@' is a valid identifier string, so it's
>   syntactically OK, right?

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

OK, will add these examples.

Thanks, Lada

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

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

---

From: Benoit Claise <[email-masked]>
Date: Wed, 1 Jul 2015 16:25:01 +0200

Hi Lada,
>> ay
>> -
>>          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?
> 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.
Ok, it was not too clear (to me) from the text.
>
>>
>>
>> - 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
> 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.
Even as example?
> 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.
ok.

Regards, Benoit

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 1 Jul 2015 16:31:21 +0200

> On 01 Jul 2015, at 16:25, Benoit Claise <[email-masked]> wrote:
> 
> Hi Lada,
>>> ay
>>> -

I will add text to explain what “distributed” means.

>> is consensus about general utility of annotations, practical definitions

Yes, I am afraid.

Lada

---

From: Benoit Claise <[email-masked]>
Date: Wed, 1 Jul 2015 16:41:30 +0200

Hi Lada,
>>> is consensus about general utility of annotations, practical definitions
I would be in favor to have at the very minimum one example.
Otherwise, it's difficult to visualize how these metadata should be used.

Regards, Benoit (as a contributor)

---

From: Andy Bierman <[email-masked]>
Date: Wed, 1 Jul 2015 08:13:26 -0700

On Wed, Jul 1, 2015 at 7:41 AM, Benoit Claise <[email-masked]> wrote:

>>>>>         operation in the NETCONF protocol (seesection 7.2 of [RFC6241]
>>>>> <https://tools.ietf.org/html/rfc6241#section-7.2>)

We support an attribute called "owner" which is basically the I2RS
client-id.
At ;least one solution proposal for I2RS is going to allow retrieval of the
metadata from the ephemeral datastore (e.g., client-id, secondary-id).
Perhaps an example like this will not be controversial.

> Regards, Benoit (as a contributor)

Andy

---

From: Kent Watsen <[email-masked]>
Date: Wed, 1 Jul 2015 16:01:19 +0000

>><snip/>

Good, but I think the text should say this explicitly.

>Yes. The description can also say that the annotation is ignored

Maybe I don't understand your response, but if we agree that annotations
are a server-level thing (not module-specific), then I do not agree that a
module's description should be able to say that an annotation should be
ignored in other modules.

>necessary to state it as a hard rule.

OK, a SHOULD or RECOMMENDED statement would help to clarify this.

>to the second entry as well.

I see, but then this make the example misleading.  I thought it was trying
to show how to place an annotation on the list as a whole.  I see now it
says "list instance", but this seems uninteresting example, as list
instances are just nodes for which how to apply annotations is already
known - there's nothing special about the node being a list element -
right?

>this cannot be represented in XML encoding (via attributes).

An annotation cannot be attached to a list as a whole?  - that seems
fundamentally broken, though I understand why you say it cannot be easily
represented in XML (via attributes).  Should we consider alternative
representations?

That said, if unavoidable, the draft needs to call that out as a
limitation somewhere, because it wan't clear to me.  Are there other
limitations that are not also not being called out?

Thanks,
Kent     (as a contributor)

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 01 Jul 2015 19:56:02 +0200 (CEST)

> I will add text to explain what “distributed” means.

Maybe call it "decentralized"?

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 02 Jul 2015 12:54:54 +0200

> Otherwise, it's difficult to visualize how these metadata should be

Sure, there will be at least one. I just have to select an appropriate
one to demonstrate the intended use without stirring up some ghosts.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 02 Jul 2015 12:55:56 +0200

> Perhaps an example like this will not be controversial.

Yes, this looks like a good one, thanks.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 02 Jul 2015 12:56:55 +0200

> Maybe call it "decentralized"?

Yes, this looks better.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 02 Jul 2015 13:28:38 +0200

OK.

> ignored in other modules.

It depends on the annotation's semantics, and it may be designed to do
something only for certain node instances (such as leafs with union
type), or for nodes in a given namespace etc. Do you think it may be a
problem?

OK.

> to show how to place an annotation on the list as a whole.  I see now
> it says "list instance", but this seems uninteresting example, as list

I will use "list entry" because the term "instance" in not defined in
YANG.

> known - there's nothing special about the node being a list element -

Do you suggest to remove the second example in that section? But you
also wanted to add an example on "anydata" that is arguable even more
alike to a container.

> represented in XML (via attributes).  Should we consider alternative

I agree it might be useful, and I was thinking about it but I haven't
found any good way for encoding it in XML, also because in XML list
entries can be interspersed with other elements.

> limitations that are not also not being called out?

Well, one could e.g. think about structured annotations but this is
again not exactly easy with XML attributes. I don't think though we can
really call it limitations - after all, the motivation for this document
was to "officialize" the use of XML attributes, so it would be a bit
weird to to make it incompatible with them.

Lada

---

From: Kent Watsen <[email-masked]>
Date: Thu, 2 Jul 2015 16:55:19 +0000

>type), or for nodes in a given namespace etc. Do you think it may be a

Those kinds of uses are fine, as they are not module-specific.  I just
want to ensure we don't ever wind up with module-specific annotations....

>also wanted to add an example on "anydata" that is arguable even more

Yes, an example for each item discussed (including anydata) is desired.
What I'm questioning here is why we need to discuss annotating list
entries at all, since they seem to follow normal rules.   If true, I
recommend removing a special section for list entries/instances entirely.

>entries can be interspersed with other elements.

Interspersed with other elements?  - I don't understand.  For instance,
assuming:

  container foobars {
    list foo {
      ...
    }
    list bar {
    }
  }

The XML would be:

  <foobars>
    <foo>...</foo>

    <foo>...</foo>

    <foo>...</foo>

    <bar>...</bar>

    <bar>...</bar>

    <bar>...</bar>

  </foobars>

Where is the interspersion?

As for how to place annotations on an XML list as a whole, I was thinking
we could use a fake first element.  For instance, the following shows an
annotation on the "bar" list:

  <foobars>
    <foo>...</foo>
    <foo>...</foo>
    <foo>...</foo>
    <bar color="red"/>   // colors entire list "red"  (notice empty
element)
    <bar>...</bar>
    <bar>...</bar>
    <bar>...</bar>
  </foobars>

But this is most likely illegal since it's not a valid instance document.
So then maybe we could use an XML comment like this:

  <foobars>
    <foo>...</foo>
    <foo>...</foo>
    <foo>...</foo>
    <!-- annotation: bar color="red" -->
    <bar>...</bar>
    <bar>...</bar>
    <bar>...</bar>
  </foobars>

Ugh, this isn't great either.  Anybody else have an idea?

>weird to to make it incompatible with them.

True, I'd rather we can find a solution for annotating XML lists.  Until
then, the draft SHOULD explicitly call it out as not supported.   Maybe
put in into an OPEN ISSUES section?

Thanks,
Kent     (as a contributor)

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 07 Jul 2015 13:53:36 +0200

> want to ensure we don't ever wind up with module-specific

A single namespace is essentially the same as a single module, isn't it?

But don't get mw wrong, syntactically annotations would be allowed
everywhere although in some places they may be a no-op.

> recommend removing a special section for list entries/instances entirely.

I don't understand. There is no special section for list entries/instances, this
is included in the section 4.2.2 (Adding Annotations to Anydata,
Container and List Instances). I agree an example should be included for
each data node type, i.e. container, list and anydata.

As for the list example, I think it is also important to show that some
entries may be decorated with annotations while other aren't.

> Where is the interspersion?

This is also valid, see sec. 7.7.6 in RFC 6020:

<foobars>
  <foo>...</foo>
  <bar>...</bar>
  <foo>...</foo>
  <bar>...</bar>
  <bar>...</bar>
  <foo>...</foo>
</foobars>

> But this is most likely illegal since it's not a valid instance

This would mess up all standard XML tools.

>     <!-- annotation: bar color="red" -->

A processing instruction would be slightly better but yes, it's ugly.

> put in into an OPEN ISSUES section?

But that means XML clients would be unable to receive some
information. Is it what we want?

Lada

---

From: Kent Watsen <[email-masked]>
Date: Tue, 7 Jul 2015 16:48:20 +0000

>everywhere although in some places they may be a no-op.

OK

<snip/>

I see, thanks.

>information. Is it what we want?

I agree that is not what we want.  Do you have any ideas other than using
a processing instruction inside an XML comment?

Thanks,
Kent  (as a contributor)