Subject: [NGO] NETCONF Notifications example

From: Andy Bierman <[email-masked]>
Date: Thu, 14 Feb 2008 12:43:39 -0800

Hi,

Here are 2 YANG files corresponding to the 2 XSDs in
draft-ietf-netconf-notifications-11.txt.  IMO, this is
a good test case, because it was done in the recent past and
we can reflect on the ease of use that we enjoyed with XSD ;-)

IMO (as former co-Chair), WG progress would have been much faster
if we were reviewing YANG modules, instead of XSDs, when deciding
if the XML syntax matched the semantics defined in the text.
This critical aspect of the data model document was painfully slow,
mistake-prone, and few people participated (because the rest
do not know XSD well enough to know if it is right, let alone
if it matches the normative text.)

That experience made me realize that XSD wasn't going to work,
and as much as I didn't want to, I agreed we really did need
to standardize a NETCONF MIB language that mere mortals could understand.

I can't possibly imagine how difficult it would be for a non-NETCONF WG
(w/o any XML experts) to develop a large domain-specific data model
like IPFIX or SIP phone provisioning for NETCONF, using XSD or RNG.

I included my auto-generated XSD files, which are very close
to pyang, to give an idea what XSD + YANG appinfo tagging
might look like.

Andy
module notifications {

    namespace "urn:ietf:params:xml:ns:netconf:notification:1.0";
    prefix "ncEvent";

    import xsd { prefix xsd; }

    organization
      "IETF NETCONF WG";

    contact
      "[email-masked]";

    description
      "Conversion of the 'ncEvent' XSD in the 
       NETCONF Notifications draft.";
         
    reference
      "draft-ietf-netconf-notifications-11.txt";

    revision 2008-02-14 {
      description "Initial version, based on -11 draft.";
    }

    typedef streamNameType {
      description
        "The name of an event stream.";
      type string;
    }

    rpc create-subscription {
      description
        "The command to create a notification subscription. It
         takes as argument the name of the notification stream
         and filter. Both of those options limit the content of
         the subscription. In addition, there are two time-related
         parameters, startTime and stopTime, which can be used to 
         select the time interval of interest to the notification
         replay feature.";

      input {
        leaf stream {
          description
            "An optional parameter that indicates which stream of events
             is of interest. If not present, then events in the default
             NETCONF stream will be sent.";
          type streamNameType;
          default "NETCONF";
        }

        anyxml filter {
          description
            "An optional parameter that indicates which subset of all
             possible events is of interest. The format of this
             parameter is the same as that of the filter parameter
             in the NETCONF protocol operations. If not present,
             all events not precluded by other parameters will 
             be sent.";
        }

        leaf startTime {
          description
            "A parameter used to trigger the replay feature and
             indicates that the replay should start at the time
             specified. If start time is not present, this is not a
             replay subscription.";
          type xsd:dateTime;
        }

        leaf stopTime {
          description
            "An optional parameter used with the optional replay
             feature to indicate the newest notifications of
             interest. If stop time is not present, the notifications
             will continue until the subscription is terminated.
             Must be used with startTime.";
          type xsd:dateTime;
        }
      }
    }

}

module nc-notifications {

    namespace "urn:ietf:params:xml:ns:netmod:notification";
    prefix "manageEvent";

    import xsd { prefix xsd; }
    import notifications { prefix ncEvent; }

    organization
      "IETF NETCONF WG";

    contact
      "[email-masked]";

    description
      "Conversion of the 'manageEvent' XSD in the NETCONF
       Notifications draft.";

    reference
      "draft-ietf-netconf-notifications-11.txt";

    revision 2008-02-14 {
      description "Initial version, based on -11 draft.";
    }

    container netconf {
      description "Top-level element in the notification namespace";

      container streams {
        description 
          "The list of event streams supported by the system. When
           a query is issued, the returned set of streams is 
           determined based on user privileges.";
        config false;

        list stream {
          description 
            "Stream name, description and other information.";
          key name;
          min-elements 1;

          leaf name {
            description
              "The name of the event stream. If this is the default
               NETCONF stream, this must have the value 'NETCONF'.";
            type ncEvent:streamNameType;
          }

          leaf description {
            description
              "A description of the event stream, including such
               information as the type of events that are sent over
               this stream.";
            type string;
            mandatory true;
          }

          leaf replaySupport {
            description
              "A description of the event stream, including such
               information as the type of events that are sent over
               this stream.";
            type boolean;
            mandatory true;
          }

          leaf replayLogCreationTime {
            description
              "The timestamp of the creation of the log used to support
               the replay function on this stream. Note that this might
               be earlier then the earliest available notification in
               the log. This object is updated if the log resets for 
               some reason.  This object MUST be present if replay is
               supported.";
            type xsd:dateTime;
          }
        }
      }
    }

    notification replayComplete {
      description
        "This notification is sent to signal the end of a replay
         portion of a subscription.";
    }

    notification notificationComplete {
      description
        "This notification is sent to signal the end of a notification
         subscription. It is sent in the case that stopTime was
         specified during the creation of the subscription..";
    }

}
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"
  targetNamespace="urn:ietf:params:xml:ns:netconf:notification:1.0"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified" attributeFormDefault="unqualified"
  xml:lang="en" version="2008-02-14"
  xmlns:ncx="http://netconfcentral.org/ncx"
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <xs:annotation>
    <xs:documentation>
      Converted from YANG file 'notifications.yang' by ncxdump version 0.8
      
      Module: notifications
      Organization: IETF NETCONF WG
      Version: 2008-02-14
      Contact: [email-masked]
    </xs:documentation>
    <xs:documentation>
      Conversion of the 'ncEvent' XSD in the
      NETCONF Notifications draft.
    </xs:documentation>
    <xs:documentation>
      draft-ietf-netconf-notifications-11.txt
    </xs:documentation>
    <xs:appinfo>
      <ncx:revision>
        <ncx:version>2008-02-14</ncx:version>
        <ncx:description>
          Initial version, based on -11 draft.
        </ncx:description>
      </ncx:revision>
    </xs:appinfo>
  </xs:annotation>

  <xs:import namespace="http://www.w3.org/XML/1998/namespace"
    schemaLocation="http://www.w3.org/XML/1998/namespace
    http://www.w3.org/2001/xml.xsd"/>

  <xs:import namespace="http://netconfcentral.org/ncx"
    schemaLocation="http://netconfcentral.org/ncx
    http://www.netconfcentral.org/xsd/ncx.xsd"/>

  <xs:simpleType name="streamNameType">
    <xs:annotation>
      <xs:documentation>The name of an event stream.</xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:string"/>
  </xs:simpleType>

  <xs:element name="create-subscription"
    substitutionGroup="nc:rpcOperation">
    <xs:annotation>
      <xs:documentation>
        The command to create a notification subscription. It
        takes as argument the name of the notification stream
        and filter. Both of those options limit the content of
        the subscription. In addition, there are two time-related
        parameters, startTime and stopTime, which can be used to
        select the time interval of interest to the notification
        replay feature.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:complexContent>
        <xs:extension base="nc:rpcOperationType">
          <xs:sequence>
            <xs:element name="stream" type="streamNameType"
              default="NETCONF" minOccurs="0">
              <xs:annotation>
                <xs:documentation>
                  An optional parameter that indicates which stream of events
                  is of interest. If not present, then events in the default
                  NETCONF stream will be sent.
                </xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element name="filter" type="xs:anyType" minOccurs="0">
              <xs:annotation>
                <xs:documentation>
                  An optional parameter that indicates which subset of all
                  possible events is of interest. The format of this
                  parameter is the same as that of the filter parameter
                  in the NETCONF protocol operations. If not present,
                  all events not precluded by other parameters will
                  be sent.
                </xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element name="startTime" type="xs:dateTime"
              minOccurs="0">
              <xs:annotation>
                <xs:documentation>
                  A parameter used to trigger the replay feature and
                  indicates that the replay should start at the time
                  specified. If start time is not present, this is not a
                  replay subscription.
                </xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element name="stopTime" type="xs:dateTime"
              minOccurs="0">
              <xs:annotation>
                <xs:documentation>
                  An optional parameter used with the optional replay
                  feature to indicate the newest notifications of
                  interest. If stop time is not present, the notifications
                  will continue until the subscription is terminated.
                  Must be used with startTime.
                </xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:any minOccurs="0" maxOccurs="unbounded"
              namespace="##other" processContents="lax"/>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:element>

</xs:schema>

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="urn:ietf:params:xml:ns:netmod:notification"
  targetNamespace="urn:ietf:params:xml:ns:netmod:notification"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified" attributeFormDefault="unqualified"
  xml:lang="en" version="2008-02-14"
  xmlns:ncx="http://netconfcentral.org/ncx"
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns:ncn="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <xs:annotation>
    <xs:documentation>
      Converted from YANG file 'nc-notifications.yang' by ncxdump version 0.8
      
      Module: nc-notifications
      Organization: IETF NETCONF WG
      Version: 2008-02-14
      Contact: [email-masked]
    </xs:documentation>
    <xs:documentation>
      Conversion of the 'manageEvent' XSD in the NETCONF
      Notifications draft.
    </xs:documentation>
    <xs:documentation>
      draft-ietf-netconf-notifications-11.txt
    </xs:documentation>
    <xs:appinfo>
      <ncx:revision>
        <ncx:version>2008-02-14</ncx:version>
        <ncx:description>
          Initial version, based on -11 draft.
        </ncx:description>
      </ncx:revision>
    </xs:appinfo>
  </xs:annotation>

  <xs:import namespace="http://www.w3.org/XML/1998/namespace"
    schemaLocation="http://www.w3.org/XML/1998/namespace
    http://www.w3.org/2001/xml.xsd"/>

  <xs:import namespace="http://netconfcentral.org/ncx"
    schemaLocation="http://netconfcentral.org/ncx
    http://www.netconfcentral.org/xsd/ncx.xsd"/>

  <xs:import
    namespace="urn:ietf:params:xml:ns:netconf:notification:1.0"
    schemaLocation="urn:ietf:params:xml:ns:netconf:notification:1.0
    http://www.netconfcentral.org/xsd/notifications.xsd"/>

  <xs:element name="netconf">
    <xs:annotation>
      <xs:documentation>
        Top-level element in the notification namespace
      </xs:documentation>
      <xs:appinfo>
        <ncx:config>true</ncx:config>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="streams">
          <xs:annotation>
            <xs:documentation>
              The list of event streams supported by the system. When
              a query is issued, the returned set of streams is
              determined based on user privileges.
            </xs:documentation>
            <xs:appinfo>
              <ncx:config>false</ncx:config>
            </xs:appinfo>
          </xs:annotation>
          <xs:complexType>
            <xs:sequence>
              <xs:element name="stream" minOccurs="1"
                maxOccurs="unbounded">
                <xs:annotation>
                  <xs:documentation>
                    Stream name, description and other information.
                  </xs:documentation>
                  <xs:appinfo>
                    <ncx:ordered-by>system</ncx:ordered-by>
                  </xs:appinfo>
                </xs:annotation>
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="name" type="ncn:streamNameType">
                      <xs:annotation>
                        <xs:documentation>
                          The name of the event stream. If this is the default
                          NETCONF stream, this must have the value 'NETCONF'.
                        </xs:documentation>
                      </xs:annotation>
                    </xs:element>
                    <xs:element name="description" type="xs:string">
                      <xs:annotation>
                        <xs:documentation>
                          A description of the event stream, including such
                          information as the type of events that are sent over
                          this stream.
                        </xs:documentation>
                        <xs:appinfo>
                          <ncx:mandatory>true</ncx:mandatory>
                        </xs:appinfo>
                      </xs:annotation>
                    </xs:element>
                    <xs:element name="replaySupport" type="xs:boolean">
                      <xs:annotation>
                        <xs:documentation>
                          A description of the event stream, including such
                          information as the type of events that are sent over
                          this stream.
                        </xs:documentation>
                        <xs:appinfo>
                          <ncx:mandatory>true</ncx:mandatory>
                        </xs:appinfo>
                      </xs:annotation>
                    </xs:element>
                    <xs:element name="replayLogCreationTime"
                      type="xs:dateTime" minOccurs="0">
                      <xs:annotation>
                        <xs:documentation>
                          The timestamp of the creation of the log used to support
                          the replay function on this stream. Note that this might
                          be earlier then the earliest available notification in
                          the log. This object is updated if the log resets for
                          some reason.  This object MUST be present if replay is
                          supported.
                        </xs:documentation>
                      </xs:annotation>
                    </xs:element>
                    <xs:any minOccurs="0" maxOccurs="unbounded"
                      namespace="##other" processContents="lax"/>
                  </xs:sequence>
                </xs:complexType>
                <xs:key name="stream_Key">
                  <xs:selector xpath="."/>
                  <xs:field xpath="name"/>
                </xs:key>
              </xs:element>
              <xs:any minOccurs="0" maxOccurs="unbounded"
                namespace="##other" processContents="lax"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"
          processContents="lax"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="replayComplete"
    substitutionGroup="ncn:notificationContent">
    <xs:annotation>
      <xs:documentation>
        This notification is sent to signal the end of a replay
        portion of a subscription.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:complexContent>
        <xs:extension base="ncn:NotificationContentType">
          <xs:sequence>
            <xs:any minOccurs="0" maxOccurs="unbounded"
              namespace="##other" processContents="lax"/>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:element>

  <xs:element name="notificationComplete"
    substitutionGroup="ncn:notificationContent">
    <xs:annotation>
      <xs:documentation>
        This notification is sent to signal the end of a notification
        subscription. It is sent in the case that stopTime was
        specified during the creation of the subscription..
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:complexContent>
        <xs:extension base="ncn:NotificationContentType">
          <xs:sequence>
            <xs:any minOccurs="0" maxOccurs="unbounded"
              namespace="##other" processContents="lax"/>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:element>

</xs:schema>

_______________________________________________
NGO mailing list
[email-masked]
http://www.ietf.org/mailman/listinfo/ngo