Subject: [netmod] questions for how yang's output statement maps to rpc-replies

From: Kent Watsen <[email-masked]>
Date: Fri, 7 Jan 2011 16:59:06 -0800

Following is from RFC 6020, section 4.2.9:

   YANG Example:

     rpc activate-software-image {
         input {
             leaf image-name {
                 type string;
             }
         }
         output {
             leaf status {
                 type string;
             }
         }
     }

   NETCONF XML Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <activate-software-image xmlns="http://acme.example.com/system">
         <image-name>acmefw-2.3</image-name>
      </activate-software-image>
     </rpc>

     <rpc-reply message-id="101"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <status xmlns="http://acme.example.com/system">
         The image acmefw-2.3 is being installed.
       </status>
     </rpc-reply>

Note that the rpc-reply uses the leaf node's name (i.e. "status") as opposed to something rpc-specific like "activate-software-image-response".  I know that a module developer could use rpc-specific values, but because they don't have to means that tools have to support that possibility.

To see where this breaks down, imagine two different RPCs, each defining an output called "status", which are distinctly different from each other.  This means that the schemas are not stateless and validators cannot treat them as such...

In trying to see if I was missing anything, I decided to analyze the XSD generated by both `yangdump` and `pyang`, to see what they do...

As you can see by looking at the attached files, I'm unable to draw any conclusions as:

1. Pyang doesn't have any output for the rpc-reply

2. Yangdump generates an output, but it's not clear what it's trying to represent due to it not being valid XSD.  FYI, here are some of the issues I found:
     - needs to be an <xs:element>
     - remove the duplicate global namespace
     - add the "xs:" prefix to all XMLSchema types
     - remove the abstract="true" for xs:element
     - missing import of netconf schema
     - invalid use of dataInlineType (should use new rpcResponseType in 4741bis)

So, here are my questions:
  - what is the valid XSD for the output statement suppose to be?
  - assuming that multiple RPCs can define the same response name, does it necessitate 
    defining each rpc-reply in its own XSD file so as avoid redundant declaration errors?

Thanks,
Kent

---

From: Andy Bierman <[email-masked]>
Date: Fri, 07 Jan 2011 18:02:38 -0800

On 01/07/2011 04:59 PM, Kent Watsen wrote:

Hi,

The XSD generation from yangdump is out-of-date.
I don't know when it will be updated to match 4741bis
and fix the known bugs.

Andy

>       - needs to be an<xs:element>

The validation is not stateless, as you noted.
A tool has to be told which rpc-reply variant is expected.

The validation for <get> and <get-config> is not schema-friendly,
since the <data> element is anyxml.

> Kent

Andy

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 08 Jan 2011 12:28:06 +0100

Hi Kent,

the RELAX NG schema generated by pyang works fine and validates your
rpc-reply, see the transcript below. The test module has two rpcs with
outputs containing leafs with the same name but conflicting type. The
RELAX NG schema for rpc-reply contains a choice between the two
alternatives.

Lada

======================================================================

$ cat rpctest.yang
module rpctest {
  namespace "http://acme.example.com/system";
  prefix rt;
  rpc activate-software-image {
    input {
      leaf image-name {
        type string;
      }
    }
    output {
      leaf status {
        type string;
      }
    }
  }
  rpc something-else {
    input {
      leaf foo-bar {
        type uint8;
      }
    }
    output {
      leaf status {
        type uint16;
      }
    }
  }
}

$ yang2dsdl -t rpc-reply rpctest.yang
== Generating RELAX NG schema './rpctest-rpc-reply.rng'
Done.

== Generating Schematron schema './rpctest-rpc-reply.sch'
Done.

== Generating DSRL schema './rpctest-rpc-reply.dsrl'
Done.

$ trang -I rng -O rnc rpctest-rpc-reply.rng rpctest-rpc-reply.rnc

$ cat rpctest-rpc-reply.rnc
default namespace = "urn:ietf:params:xml:ns:netconf:base:1.0"
namespace nma = "urn:ietf:params:xml:ns:netmod:dsdl-annotations:1"
namespace rt = "http://acme.example.com/system"

include "relaxng-lib.rnc"
start =
  element rpc-reply {
    message-id-attribute,
    (grammar {
       start =
         element rt:status { xsd:string }?
         | element rt:status { xsd:unsignedShort }?
     })
  }

$ cat rpctest.xml

$ yang2dsdl -t rpc-reply -j -s -b rpctest -v rpctest.xml
== Using pre-generated schemas

== Validating grammar and datatypes ...
rpctest.xml validates.

== Adding default values... done.

== Validating semantic constraints ...
No errors found.

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 08 Jan 2011 14:43:22 +0100 (CET)

Kent Watsen <[email-masked]> wrote:
>   - assuming that multiple RPCs can define the same response name, does it
>   - necessitate

This is a well-known problem with the XSD in 4741.  In 4741bis (thanks
to you :) the output is now also a substitution group which makes
things a bit better.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 08 Jan 2011 19:13:46 +0100

On Pá, 2011-01-07 at 16:59 -0800, Kent Watsen wrote:
> To see where this breaks down, imagine two different RPCs, each
> defining an output called "status", which are distinctly different
> from each other.  This means that the schemas are not stateless and
> validators cannot treat them as such...
> 

In fact, the idea of a common "stateless" schema for all rpc-replies is
flawed because every rpc-reply is a separate document independent of
other rpc-replies, so it only makes sense to talk about a schema for a
particular rpc-reply. Consider this: 

  rpc foo {
    output {
      leaf status {
        type string;
        must "starts-with(.,'FOO')";
      }
    }
  }
  rpc bar {
    output {
      leaf status {
        type string;
        must "starts-with(.,'BAR')";
      }
    }
  }

The must conditions are contradictory, so in order to be able to
validate a rpc-reply, one has to know whether it is a reply to "foo" or
"bar".

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Phil Shafer <[email-masked]>
Date: Sat, 8 Jan 2011 13:30:29 -0500

Kent Watsen writes:
>To see where this breaks down, imagine two different RPCs, each defining an=
> output called "status", which are distinctly different from each other.

Two top-level "status" reply elements in the same module (namespace)
with different types would be a bug in the YANG module, right?  Just
like two RPC statements with the same name would be a bug.  Should
we call this out specifically?

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Sat, 8 Jan 2011 11:19:18 -0800

Hi,

The <get> and <get-config> operations both return <data>.
IMO, the current restrictions are fine.  It is a hassle to
make sure the output child nodes are all unique within the namespace.
RFC 6020 is done.

Validating random <rpc-reply> XML documents is a low priority.
The client knows what <rpc> it called.  It can tell the random
<rpc-reply> validator which XSD to use.

Andy

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Phil Shafer
Sent: Saturday, January 08, 2011 10:30 AM
To: Kent Watsen
Cc: [email-masked]
Subject: Re: [netmod] questions for how yang's output statement maps to rpc-replies

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 08 Jan 2011 21:05:05 +0100 (CET)

> <rpc-reply> validator which XSD to use.

+1!

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 8 Jan 2011 22:31:52 +0100

> we call this out specifically?

No, each rpc output has its own namespace. In contrast, rpc names share the same namespace.

Lada

--
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Phil Shafer <[email-masked]>
Date: Sat, 8 Jan 2011 17:44:18 -0500

Ladislav Lhotka writes:
>No, each rpc output has its own namespace. In contrast, rpc names share =
>the same namespace.

I'm confused.  How does "each rpc output [have] its own namespace"?
Why doesn't the namespace of the module cover all rpc output contents?

Thanks,
 Phil

---

From: Ladislav Lhotka <[email-masked]>
Date: Sun, 09 Jan 2011 09:45:51 +0100

> Why doesn't the namespace of the module cover all rpc output contents?

Sec. 6.2.1, 7th bullet:

   o  All leafs, leaf-lists, lists, containers, choices, rpcs,
      notifications, and anyxmls defined (directly or through a uses
      statement) within a parent node or at the top level of the module
      or its submodules share the same identifier namespace.  This
      namespace is scoped to the parent node or module, unless the
      parent node is a case node.  In that case, the namespace is scoped
      to the closest ancestor node that is not a case or choice node.

So namespace of the "status" leaf in the following snippet is scoped to
its parent node which is "output". On the other hand, the name of the
rpc ("foo") is at the top-level of the module.

  rpc foo {
    output {
      leaf status {
        type string;

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Sun, 09 Jan 2011 09:04:36 -0800

>          must "starts-with(.,'FOO')";

An external <rpc-reply> validator (i.e. has no knowledge of the
corresponding <rpc>) is not really supported in NETCONF.

For example, what about these replies:

  <rpc-reply message-id="2">
    <ok />
  </rpc-reply>

This RPC defines output, so <ok/> is not a valid response
for this <rpc>.

  <rpc-reply message-id="2">
  </rpc-reply>

This RPC defines optional output, so it is possible the server
will not return it. (An if-feature in the 'status' leaf would
also cause this response for an unsupported feature.)

In hindsight, the rpc QName should have been used to wrapper any /rpc/output
content in an <rpc-reply>:

    <rpc-reply message-id="2">
      <foo>
         <status>FOObar</status>
      </foo>
    </rpc-reply>

    <rpc-reply message-id="2">
      <bar>
         <status>BARbar</status>
      </bar>
    </rpc-reply>

Andy

---

From: Kent Watsen <[email-masked]>
Date: Mon, 10 Jan 2011 11:48:58 -0800

>        must "starts-with(.,'FOO')";

Despite what section 6.2.1 says, the example below from section 4.2.9 shows the status node in the module's namespace (i.e. xmlns="http://acme.example.com/system"):

Is the example wrong?

Also, please note that with XSD(*), the only way I have been able to validate two RPC replies having the same name and namespace is to define them into distinct XSD files (see attached XSD files).  The implication of this is that a YANG-to-XSD convertor would need to generate an XSD file per RPC...

* RelaxNG and DSDL are nice, but the NetConf schema is XSD, so I'm using it

Thanks,
Kent

---

From: Kent Watsen <[email-masked]>
Date: Mon, 10 Jan 2011 12:21:22 -0800

> RELAX NG schema for rpc-reply contains a choice between the two

Hi Lada,

Thanks for the examples.  As I wrote in my other message, I'm trying to do this with XSD, as that is what the NetConf spec uses to define the transport.

I thought your idea of using a 'choice' was pretty clever, so I tried to reproduce the idea in XSD but, unfortunately, it is not legal XSD to have two elements with the same name defined under an <xs:choice>.  I then decided to try using a <xs:union>, but that also didn't work because xs:union can only be used for simpleTypes, and the NetConf XSD defines "nc:rpcResponseType" as a complexType.  This brings me to my last problem, which is that, because it must be a complexType, it cannot itself contain data; that is, I cannot generate XSD (using the 4741biz-06 XSD) to validate:

  <rpc-reply message-id="101"
             xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <status xmlns="http://acme.exampe.com/system">
      The image acmefw-2.3 is being installed
    </status>
  </rpc-reply>

I had to define an element (i.e. <value>) to place the data into:

  <rpc-reply message-id="101"
             xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <status xmlns="http://acme.exampe.com/system">
       <value>The image acmefw-2.3 is being installed</value>
    </status>
  </rpc-reply>

This means that there is no way, using the XSD that will be published in 4741biz-06, to develop XSD to validate the example shown in RFC 6020, section 4.2.9.

Perhaps the question is if we're trying to support XSD at all?  I know the Charter says the WG will only define a mapping to DSDL, but now it seems that a mapping to XSD isn’t even possible - is that OK?

Thanks,
Kent

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 11 Jan 2011 10:29:31 +0100

>          The image acmefw-2.3 is being installed.

No, it's OK, sec. 6.2.1 talks about *identifier namespaces*, i.e.
scoping of node names within a YANG module which has nothing to do with
XML namespaces - all names in a module, be it in the data part or rpc,
belong to the same XML namespace. 

> * RelaxNG and DSDL are nice, but the NetConf schema is XSD, so I'm using it

IMO the XSD schema in 4741bis is pretty much unusable for formal
validation because it tries to be a common schema for both client and
server. I summarized the problems in the now expired draft
http://tools.ietf.org/id/draft-lhotka-netconf-relaxng-00.txt
(sec. 2), I think most objections remain valid.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 11 Jan 2011 17:06:27 +0100

On Po, 2011-01-10 at 12:21 -0800, Kent Watsen wrote:
> 
> This means that there is no way, using the XSD that will be published
> in 4741biz-06, to develop XSD to validate the example shown in RFC
> 6020, section 4.2.9.
> 
> Perhaps the question is if we're trying to support XSD at all?  I know
> the Charter says the WG will only define a mapping to DSDL, but now it
> seems that a mapping to XSD isn’t even possible - is that OK?

For validation of instance documents using off-the-shelf XML tools, DSDL
currently seems to be the only serious option. The only problem is, as
you rightly say, that NETCONF messages are defined using XSD. I had
proposed RELAX NG many times for this purpose but the NETCONF WG
consensus was in favor of XSD. If there was any interest, I could
resurrect the old I-D which IMO provides quite a strict RELAX NG
validation framework for all NETCONF stuff and can be combined with data
model schemas.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Tue, 11 Jan 2011 11:06:20 -0800

Hi,

I do not think we need to redo the protocol schema in RelaxNG.
The XSD uses substitutionGroup to plug in different variants
to <rpc-reply>.  There has never been the ability to associate
a QName with a single reply.  Up until now, nobody has said
we need the client to be stateless so it can validate random <rpc-reply>
contents.  Given that the only 3 standard operations that return data
use 'anyxml' encoding, there is really not much to validate in a reply.

Andy

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Ladislav Lhotka
Sent: Tuesday, January 11, 2011 8:06 AM
To: Kent Watsen
Cc: [email-masked]
Subject: Re: [netmod] questions for how yang's output statement maps to rpc-replies

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 11 Jan 2011 21:43:36 +0100

> I do not think we need to redo the protocol schema in RelaxNG.

I don't mind the protocol schema in 4741bis, this could remain as it is if people prefer it, but perhaps a standard framework for relatively strict validation could be useful. It looks like I am not the only one who performs instance validation with xmllint or jing. And the framework is essentially done - in my expired I-D.
   
> use 'anyxml' encoding, there is really not much to validate in a reply.

Sure, validation cannot be stateless. One option that I actually plan to implement in pyang is to pass the rpc request to the validator which can then figure out the precise schema to be used for the reply. 

The anyxmls in 4741bis are just placeholders for higher-layer data. My idea is that the schemas could be layered in the same way as NETCONF protocol. 

Lada

--
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Kent Watsen <[email-masked]>
Date: Tue, 11 Jan 2011 12:48:20 -0800

> belong to the same XML namespace. 

Thanks for the clarification.  

> (sec. 2), I think most objections remain valid.

Thanks for the link - those are some pretty good points about XSD and I see how your RelaxNG schema addresses those points.   Additionally, did you see the other email I sent yesterday where I showed how the 4741bis schema could not be used to describe an RPC reply that was just an xs:simpleType?

---

From: Kent Watsen <[email-masked]>
Date: Tue, 11 Jan 2011 13:20:31 -0800

> a QName with a single reply.  

So then you agree the example in section 4.2.9 conflicts with 4741biz since the 4741biz schema requires a complexType (not a simpleType)?

> Up until now, nobody has said we need the client to be stateless so it can validate random <rpc-reply> contents.  

The original statement was too broad.  It's just that we have a single XSD file for each of our proprietary capabilities.  We have always been able to do this since each RPC-Reply has a unique name (never something generic like "status").  Thus our validators could just pass the entire XSD into `xmllint` and let it select the matching element (that's the 'stateless' part).  I suppose it was a bad assumption we could do this all along, as NetConf spec doesn't say anything about it, but now it seems that, if we want to continue using XSD, we'd need to define each RPC in its own XSD file and update our validator to pass the prc-specific XSD to `xmllint`.  Anyway, I'm sorry I brought this up, let's drop it now, it's not a WG issue.

> Given that the only 3 standard operations that return data

I'm not sure what you mean by this, but we use XSD model the exact contents of each and every one of our rpcs and rpc-replies.  Given that we have quite a number of proprietary capabilities, formal validation is pretty critical in our interoperability with 3rd-parties...

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 11 Jan 2011 22:26:38 +0100

> Thanks for the link - those are some pretty good points about XSD and I see how your RelaxNG schema addresses those points.   Additionally, did you see the other email I sent yesterday where I show…

Yes, but I must admit I don't have enough XSD expertise to help you. Use RELAX NG instead. :-)

Lada

--
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Tue, 11 Jan 2011 13:46:13 -0800

If the XSD in 4741bis has errors in it, they should be fixed.
I don't think the WG ever considered the naming conflict issues in <rpc-reply>
that a client must deal with.  Discussions were very server-focused.
I think there was a concern about wasting bandwidth with extra containers
that have no purpose.

There has been an assumption that the client will just know which RPC
was sent, and that is how the <rpc-reply> will be processed.
I think we are stuck with this assumption.

Andy

---

From: Kent Watsen <[email-masked]>
Date: Tue, 11 Jan 2011 14:00:27 -0800

> but perhaps a standard framework for relatively strict validation could be useful.
> It looks like I am not the only one who performs instance validation with xmllint
> or jing

Yes, exactly.  In fact, I imagine most device vendors run unit tests, in order to claim they implement a capability.  For them, the output schema is more important than the input schema.  On the flip side, for NMS vendors that need to validate the messages their app sends to devices, the input schema is more important than the output schema.  We do both at Juniper...albeit with XSD (because we were doing XSD before YANG was a standard)

> One option that I actually plan to implement in pyang is to pass the rpc request
> to the validator which can then figure out the precise schema to be used for the reply. 

I'm glad you brought this up.  The RNG schema that `yang2dsdl` generates is concerning as the validation can only determine that the rpc-reply is valid to a large number of matching elements.   But if there is more than one RPC returning "<status>", I want to be very sure that I'm validating against the schema for the specific RPC that was executed.  BTW, the way yang2dsdl generates the RPC scheme is less concerning, since it's not possible for two RPCs to have the same name in the same module...

PS, I also looked at the output generated by `pyang -f dsdl` and wanted to note that:

  1) it doesn't seem to be valid, `xmllint --relaxng` complains about 
     <start> having no children and <grammer> having no start

  2) the schema it generates for RPCs and RPC-Replies is very different
     than yang2dsdl's, but since they're both shipped with the same tool-chain,
     which is to be considered more official?

Thanks,
Kent

---

From: Kent Watsen <[email-masked]>
Date: Tue, 11 Jan 2011 17:03:40 -0800

> I think there was a concern about wasting bandwidth with extra containers

Ugh, I was finally able to define an XSD schema that would validate the rpc-reply example in 6020, section 4.2.9 using the 4741biz schema:

   <xs:element name="status" substitutionGroup="nc:rpcResponse">
      <xs:complexType mixed="true">
         <xs:complexContent>
            <xs:extension base="nc:rpcResponseType"/>
         </xs:complexContent>
      </xs:complexType>
   </xs:element>

I'm using the mixed="true" attribute to allow the "complexType" to contain character data.  This isn't ideal, since it's effectively like "##any", but it works, which means this conflict is resolved (yeah!)

> I think we are stuck with this assumption.

I retracted/explained my "stateless" comment in my previous email.  I'm OK with the client having to know exactly which schema to use when validating an RPC-Reply; it's a bit more involved, but tractable...

Thanks,
Kent

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 12 Jan 2011 07:58:21 +0100

On Út, 2011-01-11 at 14:00 -0800, Kent Watsen wrote:
> Yes, exactly.  In fact, I imagine most device vendors run unit tests,
> in order to claim they implement a capability.  For them, the output
> schema is more important than the input schema.  On the flip side, for
> NMS vendors that need to validate the messages their app sends to
> devices, the input schema is more important than the output schema.
> We do both at Juniper...albeit with XSD (because we were doing XSD
> before YANG was a standard)

What's the opinion of others? Would it be useful to review and resubmit
the old draft, maybe more focused on validation?
http://tools.ietf.org/id/draft-lhotka-netconf-relaxng-00.txt

...

>      <start> having no children and <grammer> having no start

Yes, this is intentional, the hybrid schema contains multiple schemas
divided by special markers in one document, so it is not a valid RELAX
NG schema. This should probably be mentioned in the YANG-to-DSDL spec
and in the pyang manpage.
 
>      which is to be considered more official?

The output of "pyang -f dsdl" is just an interim product that is used
internally by the yang2dsdl script. It cannot be used for direct
validation (except maybe informal validation by humans).

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C