Subject: [Netconf] RESTCONF YANG module changes

From: Andy Bierman <[email-masked]>
Date: Sat, 13 Sep 2014 11:19:42 -0700

Hi,

Martin suggested moving the RESTCONF API data to a real YANG module.
I have been trying to figure out how that would work. Here is the first
draft:
(It includes the new capability URI leaf-list we agreed to add)

OLD:

  ietf-restconf.yang
  Abstract module (defined in a grouping) because read-only nodes contain a
writable data root
  and not intended for NETCONF advertisement)

      +--rw restconf
         +--rw data
         +--rw modules
         |  +--rw module* [name revision]
         |     +--rw name         yang:yang-identifier
         |     +--rw revision     union
         |     +--rw schema?      empty
         |     +--rw namespace    inet:uri
         |     +--rw feature*     yang:yang-identifier
         |     +--rw deviation*   yang:yang-identifier
         |     +--rw submodule* [name revision]
         |        +--rw name        yang:yang-identifier
         |        +--rw revision    union
         |        +--rw schema?     empty
         +--rw operations
         +--rw streams
            +--rw stream* [name]
               +--rw name                        string
               +--rw description?                string
               +--rw replay-support?             boolean
               +--rw replay-log-creation-time?   yang:date-and-time
               +--rw events?                     empty

NEW:

 ietf-restconf-api.yang
  Abstract module (defined in a grouping) because read-only nodes contain a
writable data root
  and not intended for NETCONF advertisement)

      +--rw restconf
         +--rw data
         +--rw operations

ietf-restconf-state.yang
   (Almost) normal YANG module that is populated under /restconf/data

      +--ro ietf-restconf-state
        + ro capabilities
         |   +-ro capability*
        +--ro modules
         |  +--ro module* [name revision]
         |     +--ro name         yang:yang-identifier
         |     +--ro revision     union
         |     +--ro schema?      empty
         |     +--ro namespace    inet:uri
         |     +--ro feature*     yang:yang-identifier
         |     +--ro deviation*   yang:yang-identifier
         |     +--ro submodule* [name revision]
         |        +--ro name        yang:yang-identifier
         |        +--ro revision    union
         |        +--ro schema?     empty     [1]
         +--ro streams
            +--ro stream* [name]
               +--ro name                        string
               +--ro description?                string
               +--ro replay-support?             boolean
               +--ro replay-log-creation-time?   yang:date-and-time
               +--ro events?                     empty   [2]

[1]  This is the node that magically sends plain YANG  application/yang.
In NETCONF it is just an empty leaf, but in RESTCONF
it needs to be flagged somehow. It looks like application/yang.data in the
schema.

[2]  This is the node that magically sends SSE text/event-stream data until
the client
drops the connection.  In NETCONF it is just an empty leaf, but in RESTCONF
it needs to be flagged somehow. It looks like application/yang.data in the
schema.

(Notice how the name ietf-restconf.yang is now reserved for a configuration
module
for RESTCONF when we are ready for that?).

YANG extension proposal for RESTCONF:
This extension could be used in the [1] and [2] cases above to help tools
automate the processing.

   extension media-type {
       argument media-type;
       description
          "Identifies the media type associated with a YANG data node.
           Ignored unless defined as a sub-statement within a data-def-stmt.
           If this extension is not present, then the default is the media
type associated
           with the parent data-def-stmt.  If there is no parent node then
the
           media type is 'application/yang.data'.";
     }

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 14 Sep 2014 13:51:52 +0200

Hi,

can someone give a high-level overview why this is all needed given
that we have ietf-netconf-monitoring.yang? Is it because the existing
monitoring data model is not detailed enough? Or is it because it says
'netconf' in the name and thus people feel it is not applicable?

/js

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

-- 
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: Andy Bierman <[email-masked]>
Date: Sun, 14 Sep 2014 06:44:00 -0700

> 'netconf' in the name and thus people feel it is not applicable?
There is no requirement that NETCONF and RESTCONF advertise the
same set of modules or capabilities. RESTCONF does not use the
<get-schema> RPC.

RFC 6022 is written to be specific to NETCONF.  It is optional to implement
in NETCONF but this info is mandatory in RESTCONF.  We might be able
to use an update to this RFC, but it cannot be used as-is.  It would be
subject
to additions and improvements (needs both).

/js

Andy

---

From: Andy Bierman <[email-masked]>
Date: Sun, 14 Sep 2014 09:50:24 -0700

> 'netconf' in the name and thus people feel it is not applicable?
Do you think we should work on rfc6022bis instead?
I would be willing to do that.  Many of the RFC YANG objects came from yuma
modules,
but I think I was co-chair then (and IMO chairs should never be authors on
documents
in their own WG).

We have more extensions for submodules, RESTCONF, and conformance now.
Maybe other vendors do as well.

I was going to stay quiet on all the duplication, but now that you bring it
up,
an updated ietf-netconf-monitoring will have more value to operators.
E.g., I still have not figured out how to write RESTCONF text that explains
to a reader of RFC 6022 why the session data and counters are "wrong".

/js
Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 14 Sep 2014 18:55:59 +0200

> to a reader of RFC 6022 why the session data and counters are "wrong".

I would prefer if things remain consistent as much as possible. While
there might be some differences, we should try to minimize this. Things
like the module list should really be the same. I would find it
strange if one protocol interfaces provides more detail than the other.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sun, 14 Sep 2014 10:17:26 -0700

> strange if one protocol interfaces provides more detail than the other.

The ietf-restconf version of the module list has features, deviations, and a
submodule list, that are not in 6022.

I completely agree that the device should have 1 YANG library with the
same revision, features enabled, deviations applied, and same submodules.
Service-level conformance for should describe the APIs constructed from
these building blocks in the YANG library.

Not all YANG modules apply to all protocols -- e.g. <partial-lock>,
or how about ietf-netconf?  Many operations are session-specific
and do not apply to RESTCONF.  I think an identityref leaf-list can
be used in each module entry to identify the protocols that apply.

/js

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 15 Sep 2014 14:03:40 +0200 (CEST)

> submodule list, that are not in 6022.

Also, there is the 'streams' info in ietf-restconf.  For NETCONF, this
is still defined in XSD in RFC 5277.  It would be good to fix that as
well.

/martin