Re: [yang-doctors] [netconf] Yangdoctors last call review of draft-ietf-netconf-yang-push

[-netconf list]

Hi Authors,

Just want to confirm that you received this review and are working on a response.

Thanks,
Kent

> On Jan 30, 2019, at 10:51 AM, Martin Bjorklund <mbj@tail-f.com> wrote:
> 
> Hi,
> 
> This is my YANG doctor's review of draft-ietf-netconf-yang-push-21.
> 
> Reviewer: Martin Björklund
> Review result: Ready with Issues
> 
> 
> o  General
> 
>  Check the output of idnits.  Specifically, add the 2119
>  boilerplate.
> 
>  Also, since the YANG module uses 2119 language, add the YANG-ified
>  version of the boilerplate to the description statement in the
>  module, just before the copyright.
> 
> 
> o  General
> 
>  The module is inconsistently indented and formatted.  The RFC editor
>  will enforce consistent formatting, so in order to make their life
>  easier it is better to do this work before it reaches them.
> 
>  Attached is a cleaned up version of the YANG module where I have
>  done the following changes:
> 
>    o  pyang -f yang --keep-comments --yang-line-length 69
> 
>       (requires pyang 1.7.8)
> 
>    o  added newlines in long descriptions, to make separate
>       paragraphs
> 
>    o  added extra space after "." in description statement (most of
>       them already had two spaces)
> 
>    o  formatted some paragraphs (I use fill-paragraph in emacs, manually)
> 
>    o  added the 2119 boilerplate
> 
>  NOTE: I haven't done any other of the changes that I propose in
>  this review.
> 
> 
> o  Figure 6
> 
>  The tree diagram for push-change-update doesn't match the module.
> 
>  OLD:
> 
>     notifications:
>       +---n push-update
>       |  +--ro id?      sn:subscription-id
>       |  +--ro datastore-contents?   <anydata>
>       |  +--ro incomplete-update?     empty
>       +---n push-change-update {on-change}?
>          +--ro id?     sn:subscription-id
>          +--ro datastore-changes?
>          |  +--ro yang-patch
>          |     +--ro patch-id        string
>          |     +--ro ypatch:comment?    string
>          |     +--ro ypatch:edit* [edit-id]
>          |        +--ro ypatch:edit-id      string
>          |        +--ro ypatch:operation    enumeration
>          |        +--ro ypatch:target       target-resource-offset
>          |        +--ro ypatch:point?       target-resource-offset
>          |        +--ro ypatch:where?       enumeration
>          |        +--ro ypatch:value?
>          +--ro incomplete-update?    empty
> 
>  NEW:
> 
>     notifications:
>       +---n push-update
>       |  +--ro id?                   sn:subscription-id
>       |  +--ro datastore-contents?   <anydata>
>       |  +--ro incomplete-update?    empty
>       +---n push-change-update {on-change}?
>          +--ro id?                  sn:subscription-id
>          +--ro datastore-changes
>          |  +--ro yang-patch
>          |     +--ro patch-id    string
>          |     +--ro comment?    string
>          |     +--ro edit* [edit-id]
>          |        +--ro edit-id      string
>          |        +--ro operation    enumeration
>          |        +--ro target       target-resource-offset
>          |        +--ro point?       target-resource-offset
>          |        +--ro where?       enumeration
>          |        +--ro value?       <anydata>
>          +--ro incomplete-update?   empty
> 
> 
> o  Figure 6
> 
>  The purpose of including tree diagrams is to give a easy-to-read
>  overview to the reader.  When the diagram is spread out over
>  several pages, it becomes more difficult to grasp.
> 
>  In this case, I would suggest that you split the diagram into
>  smaller pieces, and place them together with the text that describe
>  them.
> 
>  For example, in 4.2 you can have the first part of the tree that
>  deals with subscription config; 4.3.1 the augmented notifs etc.
> 
> 
> o  Figure 9
> 
>  This example is difficult to read.  I suggest:
> 
>  OLD:
> 
>   <netconf:rpc message-id="101"
>     xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
>     <establish-subscription
>     xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
>     xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
>       <yp:datastore
>       xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
>         ds:operational
>       </yp:datastore>
>       <yp:datastore-xpath-filter
>       xmlns:ex="http://example.com/sample-data/1.0">
>         /ex:foo
>       </yp:datastore-xpath-filter>
>       <yp:on-change>
>         <yp:dampening-period>100</yp:dampening-period>
>       </yp:on-change>
>     </establish-subscription>
>   </netconf:rpc>
> 
>  NEW:
> 
>   <rpc message-id="101"
>        xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
>     <establish-subscription
>         xmlns=
>           "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
>         xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
>       <yp:datastore
>           xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
>         ds:operational
>       </yp:datastore>
>       <yp:datastore-xpath-filter
>           xmlns:ex="http://example.com/sample-data/1.0">
>         /ex:foo
>       </yp:datastore-xpath-filter>
>       <yp:on-change>
>         <yp:dampening-period>100</yp:dampening-period>
>       </yp:on-change>
>     </establish-subscription>
>   </rpc>
> 
> 
> o  Figure 11
> 
>  Similar in this example:
> 
>  OLD:
> 
>   <netconf:rpc message-id="102"
>      xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
>      <modify-subscription
>      xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
>      xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
>       <id>1011</id>
>       <yp:datastore
>       xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
>         ds:operational
>       </yp:datastore>
>       <yp:datastore-xpath-filter
>         xmlns:ex="http://example.com/sample-data/1.0">
>         /ex:bar
>       </yp:datastore-xpath-filter>
>       <yp:periodic>
>         <yp:period>250</yp:period>
>       </yp:periodic>
>      </modify-subscription>
>   </netconf:rpc>
> 
>  NEW:
> 
>   <rpc message-id="102"
>        xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
>     <modify-subscription
>         xmlns=
>           "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
>         xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
>       <id>1011</id>
>       <yp:datastore
>           xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
>         ds:operational
>       </yp:datastore>
>       <yp:datastore-xpath-filter
>           xmlns:ex="http://example.com/sample-data/1.0">
>         /ex:bar
>       </yp:datastore-xpath-filter>
>       <yp:periodic>
>         <yp:period>250</yp:period>
>       </yp:periodic>
>      </modify-subscription>
>   </rpc>
> 
> 
> o  Section 4.4.4
> 
>  (The figure in this example doesn't have a number)
> 
>  OLD:
> 
> <netconf:rpc message-id="103"
> xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
>   <resync-subscription
>   xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
>   xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
>     <id>1011</id>
>   </resync-subscription>
> </netconf:rpc>
> 
>  NEW:
> 
>   <rpc message-id="103"
>        xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
>     <resync-subscription
>         xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
>       <id>1011</id>
>     </resync-subscription>
>    </netconf:rpc>
> 
> o  Section 5.
> 
>  In order to get the RFC references right,  follow the pattern in
>  other documents with YANG modules; e.g. RFC 8343.  Specifically,
>  all references in RFCs must be found in the main text; this means
>  that you need to add something like:
> 
>   This YANG module imports typedefs from [RFC6991].
> 
> 
> o  import yang-patch
> 
>  OLD:
> 
>    reference
>      "RFC 8072: YANG Patch";
> 
>  NEW:
> 
>    reference
>      "RFC 8072: YANG Patch Media Type";
> 
> 
> o  typedef change-type
> 
>  The "reference" statement contains text that should be in the
>  "description" statement (this comment has been raised before on the
>  ML).
> 
>  I suggest:
> 
>  OLD:
> 
>    description
>      "Specifies different types of datastore changes.";
>    reference
>      "RFC 8072 section 2.5, with a delta that it is valid for a
>       receiver to process an update record which performs a create
>       operation on a datastore node the receiver believes exists,
>       or to process a delete on a datastore node the receiver
>       believes is missing.";
> 
>   NEW:
> 
>    description
>      "Specifies different types of datastore changes.
> 
>       This type is based on the edit operations defined for YANG
>       Patch, with the difference that it is valid for a receiver to
>       process an update record which performs a create operation on
>       a datastore node the receiver believes exists, or to process a
>       delete on a datastore node the receiver believes is missing.";
>    reference
>      "RFC 8072: YANG Patch Media Type, section 2.5";
> 
> 
> o  wrong type used (timeticks)
> 
>  This was discussed on the ML, but apparently the change wasn't
>  introduced yet.
> 
>  A couple of 'period' nodes use the type yang:timeticks, but it is
>  not an appropriate type.  RFC 6991 describes it as:
> 
>         The timeticks type represents a non-negative integer that
>         represents the time, modulo 2^32 (4294967296 decimal), in
>         hundredths of a second between two epochs.  When a schema
>         node is defined that uses this type, the description of
>         the schema node identifies both of the reference epochs.
> 
>  As Juergen pointed out, it seems you want a TimeInterval - but this
>  type is not present in RFC 6991.  So add:
> 
>    type centiseconds {
>      type uint32;
>      description
>        "A period of time, measured in units of 0.01 seconds.";
>    }
> 
>  and use that instead.
> 
> 
> o  container datastore-changes
> 
>  OLD:
> 
>    container datastore-changes {
>      description
>        "This contains the set of datastore changes of the target
>         datastore starting at the time of the previous update, per
>         the terms of the subscription.  The datastore changes are
>         encoded per RFC 8027 (YANG Patch).";
>      uses ypatch:yang-patch;
> 
>  NEW:
> 
>    container datastore-changes {
>      description
>        "This contains the set of datastore changes of the target
>         datastore starting at the time of the previous update, per
>         the terms of the subscription.";
>      uses ypatch:yang-patch;
> 
>   (The reference was not correct, and it isn't really necessary
>   anymore, since you use the grouping from yang patch.)
> 
> 
> o  leaf datastore-xpath-filter
> 
>  This leaf has the same problem that stream-xpath-filter had; it
>  doesn't work for RESTCONF.  We need to apply the same solution as
>  for stream-xpath-filter:
> 
>  OLD:
> 
>       leaf datastore-xpath-filter {
>         if-feature "sn:xpath";
>         type yang:xpath1.0;
>         description
>           "This parameter contains an XPath expression identifying
>           the portions of the target datastore to retrieve.
>           If the expression returns a node-set, all nodes in the
>           node-set are selected by the filter.  Otherwise, if the
>           expression does not return a node-set, the filter
>           doesn't select any nodes.
>           The expression is evaluated in the following XPath
>           context:
>            o  The set of namespace declarations are those in scope
>               on the 'datastore-xpath-filter' leaf element.
>            o  The set of variable bindings is empty.
>            o  The function library is the core function library, and
>               the XPath functions defined in section 10 in RFC 7950.
>            o  The context node is the root node of the target
>               datastore.";
>       }
> 
>  NEW:
> 
>       leaf datastore-xpath-filter {
>         if-feature "sn:xpath";
>         type yang:xpath1.0;
>         description
>           "This parameter contains an XPath expression identifying
>           the portions of the target datastore to retrieve.
> 
>           If the expression returns a node-set, all nodes in the
>           node-set are selected by the filter.  Otherwise, if the
>           expression does not return a node-set, the filter
>           doesn't select any nodes.
> 
>           The expression is evaluated in the following XPath
>           context:
> 
>             o   The set of namespace declarations is the set of prefix
>                 and namespace pairs for all YANG modules implemented
>                 by the server, where the prefix is the YANG module
>                 name and the namespace is as defined by the
>                 'namespace' statement in the YANG module.
> 
>                 If the leaf is encoded in XML, all namespace
>                 declarations in scope on the 'stream-xpath-filter'
>                 leaf element are added to the set of namespace
>                 declarations.  If a prefix found in the XML is
>                 already present in the set of namespace declarations,
>                 the namespace in the XML is used.
> 
>             o  The set of variable bindings is empty.
> 
>             o  The function library is the core function library, and
>                the XPath functions defined in section 10 in RFC 7950.
> 
>             o  The context node is the root node of the target
>                datastore.";
>       }
> 
> 
> o  Section A.1
> 
>  I have trouble parsing this paragraph:
> 
>   References to specific identities within the either the subscribed-
>   notifications YANG model or the yang-push YANG model may be returned
>   as part of the error responses resulting from failed attempts at
>   datastore subscription.  Following are valid errors per RPC (note:
>   throughout this section the prefix 'sn' indicates an item imported
>   from the subscribed-notifications.yang model):
> 
>  "the either the" needs to be fixed.
> 
>  Suggest you spell ou the real names of the YANG modules you refer
>  to (s/subscribed-notifications.yang
>  model/"ietf-subscribed-notifications" YANG module/  etc)
> 
> 
> o  Section A.1
> 
>  I don't think this document should repeat what's already specified
>  in the SN draft.  Specifically, I think this section should list
>  the *additional* errors that this document introduces.  I also note
>  that the list in this document is not the same as in the SN draft...
> 
>  So I suggest:
> 
>  OLD:
> 
>   establish-subscription         modify-subscription
>   ----------------------         -------------------
>    cant-exclude                   sn:filter-unsupported
>    datastore-not-subscribable     sn:insufficient-resources
>    sn:dscp-unavailable            sn:no-such-subscription
>    sn:filter-unsupported          period-unsupported
>    sn:insufficient-resources      update-too-big
>    on-change-unsupported          sync-too-big
>    on-change-sync-unsupported     unchanging-selection
>    period-unsupported
>    update-too-big                resync-subscription
>    sync-too-big                  --------------------
>    unchanging-selection           no-such-subscription-resync
>                                   sync-too-big
> 
>   delete-subscription            kill-subscription
>   ----------------------         -----------------
>    sn:no-such-subscription        sn:no-such-subscription
> 
>  NEW:
> 
>   establish-subscription         modify-subscription
>   ----------------------         -------------------
>    cant-exclude                   period-unsupported
>    datastore-not-subscribable     update-too-big
>    on-change-unsupported          sync-too-big
>    on-change-sync-unsupported     unchanging-selection
>    period-unsupported
>    update-too-big                resync-subscription
>    sync-too-big                  --------------------
>    unchanging-selection           no-such-subscription-resync
>                                   sync-too-big
> 
> 
> 
> o  Section A.2
> 
>  Similar to A.1, suggest you remove the sn: errors that are already
>  covered by SN.
> 
> 
> 
> 
> /martin
> module ietf-yang-push {
>  yang-version 1.1;
>  namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
>  prefix yp;
> 
>  import ietf-yang-types {
>    prefix yang;
>    reference
>      "RFC 6991: Common YANG Data Types";
>  }
>  import ietf-subscribed-notifications {
>    prefix sn;
>    reference
>      "draft-ietf-netconf-subscribed-notifications:
>       Customized Subscriptions to a Publisher's Event Streams
>       NOTE TO RFC Editor: Please replace above reference to
>       draft-ietf-netconf-subscribed-notifications with RFC number
>       when published (i.e. RFC xxxx).";
>  }
>  import ietf-datastores {
>    prefix ds;
>    reference
>      "RFC 8342: Network Management Datastore Architecture (NMDA)";
>  }
>  import ietf-restconf {
>    prefix rc;
>    reference
>      "RFC 8040: RESTCONF Protocol";
>  }
>  import ietf-yang-patch {
>    prefix ypatch;
>    reference
>      "RFC 8072: YANG Patch";
>  }
> 
>  organization
>    "IETF NETCONF Working Group";
>  contact
>    "WG Web:   <http://tools.ietf.org/wg/netconf/>
> 
>     WG List:  <mailto:netconf@ietf.org>
> 
>     Editor:   Alexander Clemm
>               <mailto:ludwig@clemm.org>
>     Editor:   Eric Voit
>               <mailto:evoit@cisco.com>
>     Editor:   Alberto Gonzalez Prieto
>               <mailto:agonzalezpri@vmware.com>
>     Editor:   Ambika Prasad Tripathy
>               <mailto:ambtripa@cisco.com>
>     Editor:   Einar Nilsen-Nygaard
>               <mailto:einarnn@cisco.com>
>     Editor:   Andy Bierman
>               <mailto:andy@yumaworks.com>
>     Editor:   Balazs Lengyel
>               <mailto:balazs.lengyel@ericsson.com>";
>  description
>    "This module contains YANG specifications for YANG push.
> 
>     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
>     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
>     'MAY', and 'OPTIONAL' in this document are to be interpreted as
>     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
>     they appear in all capitals, as shown here.
> 
>     Copyright (c) 2019 IETF Trust and the persons identified as
>     authors of the code.  All rights reserved.
> 
>     Redistribution and use in source and binary forms, with or
>     without modification, is permitted pursuant to, and subject to
>     the license terms contained in, the Simplified BSD License set
>     forth in Section 4.c of the IETF Trust's Legal Provisions
>     Relating to IETF Documents
>     (https://trustee.ietf.org/license-info).
> 
>     This version of this YANG module is part of RFC XXXX;
>     see the RFC itself for full legal notices.";
> 
>   // RFC Ed.: replace XXXX with actual RFC number and remove this
>   // note.
> 
>  revision 2019-01-29 {
>    description
>      "Initial revision.
>       NOTE TO RFC EDITOR:
>       (1)Please replace the above revision date to
>       the date of RFC publication when published.
>       (2) Please replace the date in the file name
>       (ietf-yang-push@2019-01-29.yang) to the date of RFC
>       publication.
>       (3) Please replace the following reference to
>       draft-ietf-netconf-yang-push-21 with RFC number when
>       published (i.e. RFC xxxx).";
>    reference
>      "draft-ietf-netconf-yang-push-21";
>  }
> 
>  /*
>   * FEATURES
>   */
> 
>  feature on-change {
>    description
>      "This feature indicates that on-change triggered subscriptions
>       are supported.";
>  }
> 
>  /*
>   * IDENTITIES
>   */
> 
>  /* Error type identities for datastore subscription  */
> 
>  identity resync-subscription-error {
>    description
>      "Problem found while attempting to fulfill an
>       'resync-subscription' RPC request.";
>  }
> 
>  identity cant-exclude {
>    base sn:establish-subscription-error;
>    description
>      "Unable to remove the set of 'excluded-changes'.  This means
>       the publisher is unable to restrict 'push-change-update's to
>       just the change types requested for this subscription.";
>  }
> 
>  identity datastore-not-subscribable {
>    base sn:establish-subscription-error;
>    base sn:subscription-terminated-reason;
>    description
>      "This is not a subscribable datastore.";
>  }
> 
>  identity no-such-subscription-resync {
>    base resync-subscription-error;
>    description
>      "Referenced subscription doesn't exist. This may be as a result
>       of a non-existent subscription ID, an ID which belongs to
>       another subscriber, or an ID for configured subscription.";
>  }
> 
>  identity on-change-unsupported {
>    base sn:establish-subscription-error;
>    description
>      "On-change is not supported for any objects which are
>       selectable by this filter.";
>  }
> 
>  identity on-change-sync-unsupported {
>    base sn:establish-subscription-error;
>    description
>      "Neither sync on start nor resynchronization are supported for
>       this subscription.  This error will be used for two
>       reasons.  First if an 'establish-subscription' RPC includes
>       'sync-on-start', yet the publisher can't support sending a
>       'push-update' for this subscription for reasons other than
>       'on-change-unsupported' or 'sync-too-big'.  And second, if the
>       'resync-subscription' RPC is invoked either for an existing
>       periodic subscription, or for an on-change subscription which
>       can't support resynchronization.";
>  }
> 
>  identity period-unsupported {
>    base sn:establish-subscription-error;
>    base sn:modify-subscription-error;
>    base sn:subscription-suspended-reason;
>    description
>      "Requested time period or dampening-period is too short.  This
>       can be for both periodic and on-change subscriptions (with or
>       without dampening.) Hints suggesting alternative periods may
>       be returned as supplemental information.";
>  }
> 
>  identity update-too-big {
>    base sn:establish-subscription-error;
>    base sn:modify-subscription-error;
>    base sn:subscription-suspended-reason;
>    description
>      "Periodic or on-change push update datatrees exceed a maximum
>       size limit.  Hints on estimated size of what was too big may
>       be returned as supplemental information.";
>  }
> 
>  identity sync-too-big {
>    base sn:establish-subscription-error;
>    base sn:modify-subscription-error;
>    base resync-subscription-error;
>    base sn:subscription-suspended-reason;
>    description
>      "Sync-on-start or resynchronization datatree exceeds a maximum
>       size limit.  Hints on estimated size of what was too big may
>       be returned as supplemental information.";
>  }
> 
>  identity unchanging-selection {
>    base sn:establish-subscription-error;
>    base sn:modify-subscription-error;
>    base sn:subscription-terminated-reason;
>    description
>      "Selection filter is unlikely to ever select datatree nodes.
>       This means that based on the subscriber's current access
>       rights, the publisher recognizes that the selection filter is
>       unlikely to ever select datatree nodes which change.  Examples
>       for this might be that node or subtree doesn't exist, read
>       access is not permitted for a receiver, or static objects that
>       only change at reboot have been chosen.";
>  }
> 
>  /*
>   * TYPE DEFINITIONS
>   */
> 
>  typedef change-type {
>    type enumeration {
>      enum create {
>        description
>          "A change that refers to the creation of a new datastore
>           node.";
>      }
>      enum delete {
>        description
>          "A change that refers to the deletion of a datastore
>           node.";
>      }
>      enum insert {
>        description
>          "A change that refers to the insertion of a new
>           user-ordered datastore node.";
>      }
>      enum move {
>        description
>          "A change that refers to a reordering of the target
>           datastore node.";
>      }
>      enum replace {
>        description
>          "A change that refers to a replacement of the target
>           datastore node's value.";
>      }
>    }
>    description
>      "Specifies different types of datastore changes.";
>    reference
>      "RFC 8072 section 2.5, with a delta that it is valid for a
>       receiver to process an update record which performs a create
>       operation on a datastore node the receiver believes exists,
>       or to process a delete on a datastore node the receiver
>       believes is missing.";
>  }
> 
>  typedef selection-filter-ref {
>    type leafref {
>      path "/sn:filters/yp:selection-filter/yp:filter-id";
>    }
>    description
>      "This type is used to reference a selection filter.";
>  }
> 
>  /*
>   * GROUP DEFINITIONS
>   */
> 
>  grouping datastore-criteria {
>    description
>      "A grouping to define criteria for which selected objects
>       from  a targeted datastore should be included in push
>       updates.";
>    leaf datastore {
>      type identityref {
>        base ds:datastore;
>      }
>      mandatory true;
>      description
>        "Datastore from which to retrieve data.";
>    }
>    uses selection-filter-objects;
>  }
> 
>  grouping selection-filter-types {
>    description
>      "This grouping defines the types of selectors for objects
>       from a datastore.";
>    choice filter-spec {
>      description
>        "The content filter specification for this request.";
>      anydata datastore-subtree-filter {
>        if-feature "sn:subtree";
>        description
>          "This parameter identifies the portions of the
>           target datastore to retrieve.";
>        reference
>          "RFC 6241: Network Configuration Protocol, Section 6.";
>      }
>      leaf datastore-xpath-filter {
>        if-feature "sn:xpath";
>        type yang:xpath1.0;
>        description
>          "This parameter contains an XPath expression identifying
>           the portions of the target datastore to retrieve.
> 
>           If the expression returns a node-set, all nodes in the
>           node-set are selected by the filter.  Otherwise, if the
>           expression does not return a node-set, the filter
>           doesn't select any nodes.
> 
>           The expression is evaluated in the following XPath
>           context:
> 
>           o  The set of namespace declarations are those in scope
>              on the 'datastore-xpath-filter' leaf element.
>           o  The set of variable bindings is empty.
>           o  The function library is the core function library, and
>              the XPath functions defined in section 10 in RFC 7950.
>           o  The context node is the root node of the target
>              datastore.";
>      }
>    }
>  }
> 
>  grouping selection-filter-objects {
>    description
>      "This grouping defines a selector for objects from a
>       datastore.";
>    choice selection-filter {
>      description
>        "The source of the selection filter applied to the
>         subscription.  This will come either referenced from a global
>         list, or be provided within the subscription itself.";
>      case by-reference {
>        description
>          "Incorporate a filter that has been configured
>           separately.";
>        leaf selection-filter-ref {
>          type selection-filter-ref;
>          mandatory true;
>          description
>            "References an existing selection filter which is to be
>             applied to the subscription.";
>        }
>      }
>      case within-subscription {
>        description
>          "Local definition allows a filter to have the same
>           lifecycle as the subscription.";
>        uses selection-filter-types;
>      }
>    }
>  }
> 
>  grouping update-policy-modifiable {
>    description
>      "This grouping describes the datastore specific subscription
>       conditions that can be changed during the lifetime of the
>       subscription.";
>    choice update-trigger {
>      description
>        "Defines necessary conditions for sending an event record to
>         the subscriber.";
>      case periodic {
>        container periodic {
>          presence "indicates a periodic subscription";
>          description
>            "The publisher is requested to notify periodically the
>             current values of the datastore as defined by the
>             selection filter.";
>          leaf period {
>            type yang:timeticks;
>            mandatory true;
>            description
>              "Duration of time which should occur between periodic
>               push updates, in one hundredths of a second.";
>          }
>          leaf anchor-time {
>            type yang:date-and-time;
>            description
>              "Designates a timestamp before or after which a series
>               of periodic push updates are determined. The next
>               update will take place at a whole multiple interval
>               from the anchor time.  For example, for an anchor time
>               is set for the top of a particular minute and a period
>               interval of a minute, updates will be sent at the top
>               of every minute this subscription is active.";
>          }
>        }
>      }
>      case on-change {
>        if-feature "on-change";
>        container on-change {
>          presence "indicates an on-change subscription";
>          description
>            "The publisher is requested to notify changes in values
>             in the datastore subset as defined by a selection
>             filter.";
>          leaf dampening-period {
>            type yang:timeticks;
>            default "0";
>            description
>              "Specifies the minimum interval between the assembly of
>               successive update records for a single receiver of a
>               subscription.  Whenever subscribed objects change, and
>               a dampening period interval (which may be zero) has
>               elapsed since the previous update record creation for
>               a receiver, then any subscribed objects and properties
>               which have changed since the previous update record
>               will have their current values marshalled and placed
>               into a new update record.";
>          }
>        }
>      }
>    }
>  }
> 
>  grouping update-policy {
>    description
>      "This grouping describes the datastore-specific subscription
>       conditions of a subscription.";
>    uses update-policy-modifiable {
>      augment "update-trigger/on-change/on-change" {
>        description
>          "Includes objects not modifiable once subscription is
>           established.";
>        leaf sync-on-start {
>          type boolean;
>          default "true";
>          description
>            "When this object is set to false, it restricts an
>             on-change subscription from sending push-update
>             notifications.  When false, pushing a full selection per
>             the terms of the selection filter MUST NOT be done for
>             this subscription.  Only updates about changes,
>             i.e. only push-change-update notifications are sent.
>             When true (default behavior), in order to facilitate a
>             receiver's synchronization, a full update is sent when
>             the subscription starts using a push-update
>             notification.  After that, push-change-update
>             notifications are exclusively sent unless the publisher
>             chooses to resync the subscription via a new push-update
>             notification.";
>        }
>        leaf-list excluded-change {
>          type change-type;
>          description
>            "Use to restrict which changes trigger an update.  For
>             example, if modify is excluded, only creation and
>             deletion of objects is reported.";
>        }
>      }
>    }
>  }
> 
>  grouping hints {
>    description
>      "Parameters associated with some error for a subscription
>       made upon a datastore.";
>    leaf period-hint {
>      type yang:timeticks;
>      description
>        "Returned when the requested time period is too short. This
>         hint can assert a viable period for either a periodic push
>         cadence or an on-change dampening interval.";
>    }
>    leaf filter-failure-hint {
>      type string;
>      description
>        "Information describing where and/or why a provided filter
>         was unsupportable for a subscription.";
>    }
>    leaf object-count-estimate {
>      type uint32;
>      description
>        "If there are too many objects which could potentially be
>         returned by the selection filter, this identifies the
>         estimate of the number of objects which the filter would
>         potentially pass.";
>    }
>    leaf object-count-limit {
>      type uint32;
>      description
>        "If there are too many objects which could be returned by
>         the selection filter, this identifies the upper limit of
>         the publisher's ability to service for this subscription.";
>    }
>    leaf kilobytes-estimate {
>      type uint32;
>      description
>        "If the returned information could be beyond the capacity
>         of the publisher, this would identify the data size which
>         could result from this selection filter.";
>    }
>    leaf kilobytes-limit {
>      type uint32;
>      description
>        "If the returned information would be beyond the capacity
>         of the publisher, this identifies the upper limit of the
>         publisher's ability to service for this subscription.";
>    }
>  }
> 
>  /*
>   * RPCs
>   */
> 
>  rpc resync-subscription {
>    if-feature "on-change";
>    description
>      "This RPC allows a subscriber of an active on-change
>       subscription to request a full push of objects.
> 
>       A successful invocation results in a push-update of all
>       datastore nodes that the subscriber is permitted to access.
>       This RPC can only be invoked on the same session on which the
>       subscription is currently active.  In case of an error, a
>       resync-subscription-error is sent as part of an error
>       response.";
>    input {
>      leaf id {
>        type sn:subscription-id;
>        mandatory true;
>        description
>          "Identifier of the subscription that is to be resynced.";
>      }
>    }
>  }
> 
>  rc:yang-data resync-subscription-error {
>    container resync-subscription-error {
>      description
>        "If a 'resync-subscription' RPC fails, the subscription is
>         not resynced and the RPC error response MUST indicate the
>         reason for this failure.  This yang-data MAY be inserted as
>         structured data within a subscription's RPC error response
>         to indicate the failure reason.";
>      leaf reason {
>        type identityref {
>          base resync-subscription-error;
>        }
>        mandatory true;
>        description
>          "Indicates the reason why the publisher has declined a
>           request for subscription resynchronization.";
>      }
>      uses hints;
>    }
>  }
> 
>  augment "/sn:establish-subscription/sn:input" {
>    description
>      "This augmentation adds additional subscription parameters
>       that apply specifically to datastore updates to RPC input.";
>    uses update-policy;
>  }
> 
>  augment "/sn:establish-subscription/sn:input/sn:target" {
>    description
>      "This augmentation adds the datastore as a valid target
>       for the subscription to RPC input.";
>    case datastore {
>      description
>        "Information specifying the parameters of an request for a
>         datastore subscription.";
>      uses datastore-criteria;
>    }
>  }
> 
>  rc:yang-data establish-subscription-datastore-error-info {
>    container establish-subscription-datastore-error-info {
>      description
>        "If any 'establish-subscription' RPC parameters are
>         unsupportable against the datastore, a subscription is not
>         created and the RPC error response MUST indicate the reason
>         why the subscription failed to be created.  This yang-data
>         MAY be inserted as structured data within a subscription's
>         RPC error response to indicate the failure reason.  This
>         yang-data MUST be inserted if hints are to be provided back
>         to the subscriber.";
>      leaf reason {
>        type identityref {
>          base sn:establish-subscription-error;
>        }
>        description
>          "Indicates the reason why the subscription has failed to
>           be created to a targeted datastore.";
>      }
>      uses hints;
>    }
>  }
> 
>  augment "/sn:modify-subscription/sn:input" {
>    description
>      "This augmentation adds additional subscription parameters
>       specific to datastore updates.";
>    uses update-policy-modifiable;
>  }
> 
>  augment "/sn:modify-subscription/sn:input/sn:target" {
>    description
>      "This augmentation adds the datastore as a valid target
>       for the subscription to RPC input.";
>    case datastore {
>      description
>        "Information specifying the parameters of an request for a
>         datastore subscription.";
>      uses datastore-criteria;
>    }
>  }
> 
>  rc:yang-data modify-subscription-datastore-error-info {
>    container modify-subscription-datastore-error-info {
>      description
>        "This yang-data MAY be provided as part of a subscription's
>         RPC error response when there is a failure of a
>         'modify-subscription' RPC which has been made against a
>         datastore.  This yang-data MUST be used if hints are to be
>         provides back to the subscriber.";
>      leaf reason {
>        type identityref {
>          base sn:modify-subscription-error;
>        }
>        description
>          "Indicates the reason why the subscription has failed to
>           be modified.";
>      }
>      uses hints;
>    }
>  }
> 
>  /*
>   * NOTIFICATIONS
>   */
> 
>  notification push-update {
>    description
>      "This notification contains a push update, containing data
>       subscribed to via a subscription.  This notification is sent
>       for periodic updates, for a periodic subscription.  It can
>       also be used for synchronization updates of an on-change
>       subscription.  This notification shall only be sent to
>       receivers of a subscription.  It does not constitute a
>       general-purpose notification that would be subscribable as
>       part of the NETCONF event stream by any receiver.";
>    leaf id {
>      type sn:subscription-id;
>      description
>        "This references the subscription which drove the
>         notification to be sent.";
>    }
>    anydata datastore-contents {
>      description
>        "This contains the updated data.  It constitutes a snapshot
>         at the time-of-update of the set of data that has been
>         subscribed to.  The snapshot corresponds to the same
>         snapshot that would be returned in a corresponding get
>         operation with the same selection filter parameters
>         applied.";
>    }
>    leaf incomplete-update {
>      type empty;
>      description
>        "This is a flag which indicates that not all datastore
>         nodes subscribed to are included with this update.  In
>         other words, the publisher has failed to fulfill its full
>         subscription obligations, and despite its best efforts is
>         providing an incomplete set of objects.";
>    }
>  }
> 
>  notification push-change-update {
>    if-feature "on-change";
>    description
>      "This notification contains an on-change push update. This
>       notification shall only be sent to the receivers of a
>       subscription; it does not constitute a general-purpose
>       notification.";
>    leaf id {
>      type sn:subscription-id;
>      description
>        "This references the subscription which drove the
>         notification to be sent.";
>    }
>    container datastore-changes {
>      description
>        "This contains the set of datastore changes of the target
>         datastore starting at the time of the previous update, per
>         the terms of the subscription.  The datastore changes are
>         encoded per RFC 8027 (YANG Patch).";
>      uses ypatch:yang-patch;
>    }
>    leaf incomplete-update {
>      type empty;
>      description
>        "The presence of this object indicates not all changes which
>         have occurred since the last update are included with this
>         update.  In other words, the publisher has failed to
>         fulfill its full subscription obligations, for example in
>         cases where it was not able to keep up with a change
>         burst.";
>    }
>  }
> 
>  augment "/sn:subscription-started" {
>    description
>      "This augmentation adds datastore-specific objects to
>       the notification that a subscription has started.";
>    uses update-policy;
>  }
> 
>  augment "/sn:subscription-started/sn:target" {
>    description
>      "This augmentation allows the datastore to be included as
>       part of the notification that a subscription has started.";
>    case datastore {
>      uses datastore-criteria {
>        refine "selection-filter/within-subscription" {
>          description
>            "Specifies the selection filter and where it originated
>             from.  If the 'selection-filter-ref' is populated, the
>             filter within the subscription came from the 'filters'
>             container.  Otherwise it is populated in-line as part of
>             the subscription itself.";
>        }
>      }
>    }
>  }
> 
>  augment "/sn:subscription-modified" {
>    description
>      "This augmentation adds datastore-specific objects to
>       the notification that a subscription has been modified.";
>    uses update-policy;
>  }
> 
>  augment "/sn:subscription-modified/sn:target" {
>    description
>      "This augmentation allows the datastore to be included as
>       part of the notification that a subscription has been
>       modified.";
>    case datastore {
>      uses datastore-criteria {
>        refine "selection-filter/within-subscription" {
>          description
>            "Specifies where the selection filter, and where it came
>             from within the subscription and then populated within
>             this notification.  If the 'selection-filter-ref' is
>             populated, the filter within the subscription came from
>             the 'filters' container.  Otherwise it is populated
>             in-line as part of the subscription itself.";
>        }
>      }
>    }
>  }
> 
>  /*
>   * DATA NODES
>   */
> 
>  augment "/sn:filters" {
>    description
>      "This augmentation allows the datastore to be included as part
>       of the selection filtering criteria for a subscription.";
>    list selection-filter {
>      key "filter-id";
>      description
>        "A list of pre-configured filters that can be applied
>         to datastore subscriptions.";
>      leaf filter-id {
>        type string;
>        description
>          "An identifier to differentiate between selection
>           filters.";
>      }
>      uses selection-filter-types;
>    }
>  }
> 
>  augment "/sn:subscriptions/sn:subscription" {
>    when 'yp:datastore';
>    description
>      "This augmentation adds many datastore specific objects to a
>       subscription.";
>    uses update-policy;
>  }
> 
>  augment "/sn:subscriptions/sn:subscription/sn:target" {
>    description
>      "This augmentation allows the datastore to be included as
>       part of the selection filtering criteria for a subscription.";
>    case datastore {
>      uses datastore-criteria;
>    }
>  }
> }
> _______________________________________________
> netconf mailing list
> netconf@ietf.org
> https://www.ietf.org/mailman/listinfo/netconf