Re: [yang-doctors] [netconf] Yangdoctors last call review of draft-ietf-netconf-yang-push
Kent Watsen <kent@watsen.net> Tue, 05 February 2019 01:45 UTC
Return-Path: <01000168bb54cbd0-0ca31a17-fe4e-434e-840b-ab6f86d73c20-000000@amazonses.watsen.net>
X-Original-To: yang-doctors@ietfa.amsl.com
Delivered-To: yang-doctors@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 403C4130F33; Mon, 4 Feb 2019 17:45:30 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level:
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=amazonses.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id MlGMJUQNssFf; Mon, 4 Feb 2019 17:45:25 -0800 (PST)
Received: from a8-83.smtp-out.amazonses.com (a8-83.smtp-out.amazonses.com [54.240.8.83]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id EB8D2130F28; Mon, 4 Feb 2019 17:45:24 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/simple; s=ug7nbtf4gccmlpwj322ax3p6ow6yfsug; d=amazonses.com; t=1549331123; h=Content-Type:Mime-Version:Subject:From:In-Reply-To:Date:Cc:Content-Transfer-Encoding:Message-Id:References:To:Feedback-ID; bh=DvdkjhbF2UBb10DFOCoDuDQf3YkZxYVc5VS5l4QHwNY=; b=OaRKkND0gvMXKJeU3YHzEOVwMRDhtBbHVjdFojjWmfJ/5dxLvaZUDemnFEv6BPMa JPcYpfwBy6OEJIRaLlsWVBGhfbtTm+P7CdesMIfyRJzahoza7CWYnypRAsr3S9elpKr hWMt9l4BulcwdZk+dG8ApWA6+B7TWHPZ8E6vGtcs=
Content-Type: text/plain; charset="utf-8"
Mime-Version: 1.0 (Mac OS X Mail 12.2 \(3445.102.3\))
From: Kent Watsen <kent@watsen.net>
In-Reply-To: <20190130.165118.1684515639662649114.mbj@tail-f.com>
Date: Tue, 05 Feb 2019 01:45:23 +0000
Cc: YANG Doctors <yang-doctors@ietf.org>, Martin Bjorklund <mbj@tail-f.com>
Content-Transfer-Encoding: quoted-printable
Message-ID: <01000168bb54cbd0-0ca31a17-fe4e-434e-840b-ab6f86d73c20-000000@email.amazonses.com>
References: <20190130.165118.1684515639662649114.mbj@tail-f.com>
To: draft-ietf-netconf-yang-push.all@ietf.org
X-Mailer: Apple Mail (2.3445.102.3)
X-SES-Outgoing: 2019.02.05-54.240.8.83
Feedback-ID: 1.us-east-1.DKmIRZFhhsBhtmFMNikgwZUWVrODEw9qVcPhqJEI2DA=:AmazonSES
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/ulv0EuWgqflnnNlw5qmGwMZiO6A>
Subject: Re: [yang-doctors] [netconf] Yangdoctors last call review of draft-ietf-netconf-yang-push
X-BeenThere: yang-doctors@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Email list of the yang-doctors directorate <yang-doctors.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/yang-doctors/>
List-Post: <mailto:yang-doctors@ietf.org>
List-Help: <mailto:yang-doctors-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 05 Feb 2019 01:45:30 -0000
[-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
- [yang-doctors] Yangdoctors last call review of dr… Martin Bjorklund
- Re: [yang-doctors] [netconf] Yangdoctors last cal… Kent Watsen
- Re: [yang-doctors] [netconf] Yangdoctors last cal… Alexander Clemm
- Re: [yang-doctors] [netconf] Yangdoctors last cal… Martin Bjorklund
- Re: [yang-doctors] [netconf] Yangdoctors last cal… Alexander Clemm