Subject: [netmod] AD review: draft-ietf-netmod-yang-json-07

From: Benoit Claise <[email-masked]>
Date: Wed, 3 Feb 2016 11:19:33 +0100

Dear all,

I understood from the chairs that draft-ietf-netmod-yang-json is now 
ready and that the write-up will be completed end of this week.
In order to speed up the publication, here is my AD review.

- Editorial:

    This document defines encoding rules for representing configuration,
    state data, RPC operation or action input and output parameters, and
    notifications defined using YANG as JavaScript Object Notation (JSON)
    text.

"RPC operation or action input and output parameters"
", or ... and, " it's always complicated.
Why not only "RPC operation or action"?

At the very minimum "input and output parameters" to "input/output 
parameters"

Same remark for section 1.1

    The specification of YANG 1.1 data modelling language
    [I-D.ietf-netmod-rfc6020bis 
<https://tools.ietf.org/html/draft-ietf-netmod-yang-json-06#ref-I-D.ietf-netmod-rfc6020bis>] defines only XML encoding for data
    instances, i.e., contents of configuration datastores, state data,
    RPC operation or action input and output parameters, and event
    notifications.

If you want to extend, also fine.

    The specification of YANG 1.1 data modelling language
    [I-D.ietf-netmod-rfc6020bis 
<https://tools.ietf.org/html/draft-ietf-netmod-yang-json-06#ref-I-D.ietf-netmod-rfc6020bis>] defines only XML encoding for data
    instances, i.e., contents of configuration datastores, state data,
    RPC operation input and output parameters, action input and output
    parameters, and event notifications.

Btw, "RPC", "action" and "input and output parameters" are only 
mentioned in the abstract and this introduction, not anymore in the body 
of the document. There is nothing specific to these worth noting? Not 
even an example?

- Editorial

In the introduction, you might want to complete the last sentence

NEW:
    The specification of YANG 1.1 data modelling language
    [I-D.ietf-netmod-rfc6020bis 
<https://tools.ietf.org/html/draft-ietf-netmod-yang-json-07#ref-I-D.ietf-netmod-rfc6020bis>] defines only XML encoding for data
    instances, i.e., contents of configuration datastores, state data,
    RPC operation or action input and output parameters, and event
    notifications.  The aim of this document is to define rules for
    encoding the same data as JavaScript Object Notation (JSON)
    text [RFC7159 <https://tools.ietf.org/html/rfc7159>].

NEW:
    The specification of YANG 1.1 data modelling language
    [I-D.ietf-netmod-rfc6020bis 
<https://tools.ietf.org/html/draft-ietf-netmod-yang-json-07#ref-I-D.ietf-netmod-rfc6020bis>] defines only XML encoding for data
    instances, i.e., contents of configuration datastores, state data,
    RPC operation or action input and output parameters, and event
    notifications.  The aim of this document is to define rules for
    encoding the same data as JavaScript Object Notation (JSON)
    text [RFC7159 <https://tools.ietf.org/html/rfc7159>], most precisely the Internet JSON (I-JSON) restricted
    profile [RFC7493 <https://tools.ietf.org/html/rfc7493>].

-
section 2:

    The following terms are defined in [I-D.ietf-netmod-rfc6020bis 
<https://tools.ietf.org/html/draft-ietf-netmod-yang-json-07#ref-I-D.ietf-netmod-rfc6020bis>]:
       ...

    o  identity,

There is no identity definition in the RFC 6020 terminology section.
Are you referring to the identity statement, 
https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis-09#section-7.18 ?

- Editorial.

OLD:
	An object member name MUST be in one of the following forms:
NEW:
	A JSON object member name MUST be encoded in one of the following forms:

-
   module foomod {

      namespace"http://example.com/foomod";

      prefix "foo";

      container top {
        leaf foo {
          type uint8;
        }
      }
    }

Use "example-" in the module name, as mentioned inhttps://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-05:

        Example modules are non-normative, and SHOULD be named with the
        prefix "example-".

Same remark for module barmod (and btw, pay attention to the "import 
foomod") and module exmod

- Editorial (Appendix A):

OLD:
    The "if-mib" feature defined in the "ietf-
    interfaces" module is considered to be active.

NEW:
    The "if-mib" feature defined in the "ietf-
    interfaces" module is supported.

Regards, Benoit

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 3 Feb 2016 11:49:46 +0100

On Wed, Feb 03, 2016 at 11:19:33AM +0100, Benoit Claise wrote:

> Use "example-" in the module name, as mentioned 
> inhttps://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-05:
> 

I still believe the text in draft-ietf-netmod-rfc6087bis-05 needs
fixing to distinguish between examples that should be subject to
validation and examples that are just there for documentation purposes
and which are typically designed to be incomplete in order to aid the
reader.

/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: Ladislav Lhotka <[email-masked]>
Date: Wed, 03 Feb 2016 13:06:26 +0100

Hi Benoit,

thank you for the review, please see my responses inline.

> Why not only "RPC operation or action"?

Because we aren't encoding operations, just their parameters.

> At the very minimum "input and output parameters" to "input/output 

OK, so how about using just "parameters of RPC operations or actions" in
the abstract, and "input/output parameters of RPC operations or actions"
elsewhere?

> of the document. There is nothing specific to these worth noting? Not 

This document is about encoding YANG data nodes, and the rules are the
same for any data tree. Encoding of operations or notifications is a
subject for a protocol spec, and RESTCONF does provide examples.

>     profile [RFC7493 <https://tools.ietf.org/html/rfc7493>].

I would say that for the introduction the more general term (JSON) is
appropriate, the reasons for sticking to I-JSON are explained later. In
fact, this document specifies a profile that's even more restricted than
I-JSON.

> There is no identity definition in the RFC 6020 terminology section.

Maybe it is an omission in 6020bis?

> https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis-09#section-7.18

No, I am referring to a "globally unique, abstract, and untyped
identity" (sec. 7.18 in 6020bis) that's defined by an "identity" statement.

> 	A JSON object member name MUST be encoded in one of the following forms:

OK.

> foomod") and module exmod

I agree with Juergen that 6087bis should distinguish between complete
example modules and short module snippets that are used for explaining a
certain YANG language or encoding issue. If you look at this particular
example, then changing the JSON document on p. 6 to

   {
     "example-foomod:top": {
       "foo": 54,
       "example-barmod:bar": true
     }
   }

would IMO just add noise and blur the message the example is supposed to
convey.

>     interfaces" module is supported.

Yes, right.

Thanks, Lada

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

---

From: Benoit Claise <[email-masked]>
Date: Wed, 3 Feb 2016 13:58:00 +0100

Hi Lada,

Thanks for the quick reply.
> Because we aren't encoding operations, just their parameters.
Good point.
> the abstract, and "input/output parameters of RPC operations or actions"
Sure.
> same for any data tree.
Not worth mentioning something such as
" There is nothing specific to input and output parameters compared to 
any other data tree..."?
> Encoding of operations or notifications is a
Fair enough.
> Maybe it is an omission in 6020bis?
Ok, let's fix it in 6020bis then.
> would IMO just add noise and blur the message the example is supposed to
So please fix the text in 6087bis.
Until it's done, I'll stick to the current rule.

Regards, Benoit

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 3 Feb 2016 14:28:23 +0100

> On 03 Feb 2016, at 13:58, Benoit Claise <[email-masked]> wrote:
> 
> Hi Lada,
> 

Done.

> " There is nothing specific to input and output parameters compared to any other data tree..."?

OK, I'll add such a note.

...

> Until it's done, I'll stick to the current rule.

I don't want to be excessively bureaucratic but, strictly speaking, current rules are those of RFC 6087 that contains no such requirement, so we should be OK for now. And I think there is enough consensus to change the corresponding 6087bis text - after all, 6020bis also has example modules whose names don't start with "example-".

Thanks, Lada

---

From: Benoit Claise <[email-masked]>
Date: Wed, 3 Feb 2016 14:37:12 +0100

Hi Lada,
> I don't want to be excessively bureaucratic but, strictly speaking, current rules are those of RFC 6087 that contains no such requirement, so we should be OK for now. And I think there is enough consensus
so Jürgen and you?
> to change the corresponding 6087bis text - after all, 6020bis also has example modules whose names don't start with "example-".
I'll still have to review it and that will be one of my comments, for 
sure. Consistency first.

Regards ,Benoit

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 3 Feb 2016 14:47:23 +0100

> On 03 Feb 2016, at 14:37, Benoit Claise <[email-masked]> wrote:
> 
> Hi Lada,
>> 

I guess Martin as well, given that 6020bis doesn't follow that rule.

Lada

> I'll still have to review it and that will be one of my comments, for sure. Consistency first.
> 
> Regards ,Benoit
>

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 03 Feb 2016 15:35:43 +0100 (CET)

> > Benoit Claise <[email-masked]> writes:

[...]

> Ok, let's fix it in 6020bis then.

Ok.  First I wrote:

 o  identity: A globally unique, abstract, and untyped identity.

But this is kind of recursive...

 o  identity: A globally unique, abstract, and untyped label.

Any other proposal?

/martin

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 3 Feb 2016 15:40:40 +0100

> On 03 Feb 2016, at 15:35, Martin Bjorklund <[email-masked]> wrote:
> 

s/label/name/ ?

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 03 Feb 2016 17:33:28 +0100 (CET)

Ladislav Lhotka <[email-masked]> wrote:
> >> I don't want to be excessively bureaucratic but, strictly
> speaking, current rules are those of RFC 6087 that contains no such
> requirement, so we should be OK for now. And I think there is enough
> consensus
> > so Jürgen and you?
> 

I agree that not all modules must compile, e.g. we have things like:

  module example-foo {
     ...
     container bar { ... }
  }

Having said that, in the upcoming version of 6020bis, I have changed
things like "module acme-system" to "module example-system".

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 3 Feb 2016 22:11:59 +0100

> On 03 Feb 2016, at 17:33, Martin Bjorklund <[email-masked]> wrote:
> 

OK, so I will also add the "example-" prefix in yang-json.

Lada

---

From: Mahesh Jethanandani <[email-masked]>
Date: Wed, 3 Feb 2016 13:38:45 -0800

> On Feb 3, 2016, at 2:49 AM, Juergen Schoenwaelder <[email-masked]> wrote:
> 

I agree. Currently there is no way to distinguish between models that are examples, meant to be extracted and validated, and what I call snippets of an example that are designed to incomplete and for demonstrating a point. 

Should there be a stipulation in 6087bis that incomplete examples should NOT use the prefix example-?

> /js

Mahesh Jethanandani
[email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Wed, 3 Feb 2016 13:59:18 -0800

Hi,

I entered a new 6087bis issue:
https://github.com/netmod-wg/rfc6087bis/issues/27

I agree the conventions need to be spelled out.
IMO there are many problematic examples in 6020bis.
The convention "..." is used and some newbie could think
it was some valid YANG syntax.  There are also example
modules that use prefixes although no prefix-stmt or import-stmt
is shown to match up the prefix.

This is a bigger problem than automated tools extracting modules.
People learn from examples (more than we would like) so it needs
to be clear in every YANG draft whether a YANG example
is complete vs. trimmed for readability and not meant to be compiled.

Let's not use 'example' as a hack to indicate 1 or the other.
Compiler writers want deterministic syntax, not ad-hoc conventions.

There are 3 scenarios:

1) normative: has <CODE BEGINS> and complete YANG module

2) example: no <CODE BEGINS> but complete YANG module,
    intended to be compiled

3) snippet: no <CODE BEGINS> and not complete, not intended to be compiled

So we cannot tell the difference between (2) and (3).

IMO we should have <EXAMPLE BEGINS> for (2) so it can be
extracted automatically and distinguished from (3).

Andy

On Wed, Feb 3, 2016 at 1:38 PM, Mahesh Jethanandani <[email-masked]
> wrote:

>
> On Feb 3, 2016, at 2:49 AM, Juergen Schoenwaelder <
> [email-masked]> wrote:
>
> I agree. Currently there is no way to distinguish between models that are
> examples, meant to be extracted and validated, and what I call snippets of
> an example that are designed to incomplete and for demonstrating a point.
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 04 Feb 2016 08:42:15 +0100

> So we cannot tell the difference between (2) and (3).

I think the "example-" prefix could be such a discriminator, to be used
at I-D author's discretion. It's better than nothing.

Lada