--- 1/draft-ietf-netconf-yang-patch-06.txt 2015-12-15 10:15:15.033504765 -0800 +++ 2/draft-ietf-netconf-yang-patch-07.txt 2015-12-15 10:15:15.085506054 -0800 @@ -1,21 +1,21 @@ Network Working Group A. Bierman Internet-Draft YumaWorks Intended status: Standards Track M. Bjorklund -Expires: April 20, 2016 Tail-f Systems +Expires: June 17, 2016 Tail-f Systems K. Watsen Juniper Networks - October 18, 2015 + December 15, 2015 YANG Patch Media Type - draft-ietf-netconf-yang-patch-06 + draft-ietf-netconf-yang-patch-07 Abstract This document describes a method for applying patches to NETCONF datastores using data defined with the YANG data modeling language. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. @@ -23,78 +23,79 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on April 20, 2016. + This Internet-Draft will expire on June 17, 2016. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5 + 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 4 1.1.5. YANG Patch . . . . . . . . . . . . . . . . . . . . . 5 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 - 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Target Resource . . . . . . . . . . . . . . . . . . . . . 6 2.2. yang-patch Input . . . . . . . . . . . . . . . . . . . . 6 2.3. yang-patch-status Output . . . . . . . . . . . . . . . . 7 2.4. Target Data Node . . . . . . . . . . . . . . . . . . . . 7 2.5. Edit Operations . . . . . . . . . . . . . . . . . . . . . 8 2.6. Error Handling . . . . . . . . . . . . . . . . . . . . . 8 2.7. yang-patch RESTCONF Capability . . . . . . . . . . . . . 9 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 + 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 18 4.2. application/yang.patch Media Types . . . . . . . . . . . 18 - 4.3. application/yang.patch-status Media Types . . . . . . . . 19 + 4.3. application/yang.patch-status Media Types . . . . . . . . 18 4.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 19 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19 - 6. Normative References . . . . . . . . . . . . . . . . . . . . 20 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 21 + 6. Normative References . . . . . . . . . . . . . . . . . . . . 19 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 20 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 21 - B.1. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 21 - B.2. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 21 - B.3. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 21 - B.4. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 22 - B.5. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 22 - B.6. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 22 - B.7. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 23 + B.1. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 21 + B.2. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 21 + B.3. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 21 + B.4. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 21 + B.5. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 22 + B.6. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 22 + B.7. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 22 + B.8. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 23 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 23 Appendix D. Example YANG Module . . . . . . . . . . . . . . . . 23 D.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 24 D.1.1. Add Resources: Error . . . . . . . . . . . . . . . . 24 D.1.2. Add Resources: Success . . . . . . . . . . . . . . . 27 - D.1.3. Move list entry example . . . . . . . . . . . . . . . 28 + D.1.3. Move list entry example . . . . . . . . . . . . . . . 29 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 1. Introduction There is a need for standard mechanisms to patch NETCONF [RFC6241] datastores which contain conceptual data that conforms to schema specified with YANG [RFC6020]. An "ordered edit list" approach is needed to provide client developers with a simpler edit request format that can be more efficient and also allow more precise client control of the transaction procedure than existing mechanisms. @@ -391,28 +390,29 @@ The "ietf-restconf" module from [I-D.ietf-netconf-restconf] is used by this module for the 'restconf-media-type' extension definition. RFC Ed.: update the date below with the date of RFC publication and remove this note. file "ietf-yang-patch@2015-04-30.yang" module ietf-yang-patch { + yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch"; prefix "ypatch"; import ietf-yang-types { prefix yang; } import ietf-restconf { prefix rc; - revision-date 2015-10-07; + revision-date 2015-10-18; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: WG List: WG Chair: Mehmet Ersue @@ -449,30 +449,31 @@ Relating to IETF Documents (http://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. // RFC Ed.: remove this note - // Note: extracted from draft-ietf-netconf-yang-patch-06.txt + // Note: extracted from draft-ietf-netconf-yang-patch-07.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. - revision 2015-06-04 { + revision 2015-12-15 { description "Initial revision."; reference "RFC XXXX: YANG Patch Media Type."; } + typedef target-resource-offset { type yang:xpath1.0; description "Contains an XPath absolute path expression identifying a sub-resource within the target resource. The document root for this XPath expression is the target resource that is specified in the protocol operation (e.g., the URI for the PATCH request)."; } @@ -603,32 +604,32 @@ enum remove { description "Delete the target node if it currently exists."; } } mandatory true; description "The datastore operation requested for the associated edit entry"; } + leaf target { type target-resource-offset; mandatory true; description "Identifies the target data resource for the edit operation."; } leaf point { - when "(../operation = 'insert' or " + - "../operation = 'move') and " + - "(../where = 'before' or ../where = 'after')" { + when "(../operation = 'insert' or ../operation = 'move') " + + "and (../where = 'before' or ../where = 'after')" { description "Point leaf only applies for insert or move operations, before or after an existing entry."; } type target-resource-offset; description "The absolute URL path for the data node that is being used as the insertion point or move point for the target of this edit entry."; } @@ -663,66 +664,58 @@ } default last; description "Identifies where a data resource will be inserted or moved. YANG only allows these operations for list and leaf-list data nodes that are ordered-by user."; } - anyxml value { - when "(../operation = 'create' or " + - "../operation = 'merge' " + - "or ../operation = 'replace' or " + - "../operation = 'insert')" { + anydata value { + when "../operation = 'create' " + + "or ../operation = 'merge' " + + "or ../operation = 'replace' " + + "or ../operation = 'insert'" { description "Value node only used for create, merge, replace, and insert operations"; } description - "Value used for this edit operation. - The anyxml value MUST represent a container with - exactly one child node, which MUST identify the - target resource associated with the 'target' leaf. - - The descendants of this node MUST NOT contain - an 'anyxml' data node. Only 'list', 'container', - 'leaf', and 'leaf-list' data nodes can appear as - descendant nodes of this object. + "Value used for this edit operation. The anydata 'value' + contains the target resource associated with the + 'target' leaf. For example, suppose the target node is a YANG container named foo: container foo { leaf a { type string; } leaf b { type int32; } } - The value node will contain one instance of foo: + The 'value' node will contain one instance of foo: some value 42 - "; } } } } // grouping yang-patch grouping yang-patch-status { - description "A grouping that contains a YANG container representing the syntax and semantics of YANG Patch status response message."; container yang-patch-status { description "A container representing the response message sent by the server after a YANG Patch edit request message has been processed."; @@ -960,41 +950,51 @@ those of the author(s) and do not necessarily reflect the views of The Space & Terrestrial Communications Directorate (S&TCD). Appendix B. Change Log -- RFC Ed.: remove this section before publication. The YANG Patch issue tracker can be found here: https://github.com/ netconf-wg/yang-patch/issues -B.1. v05 to v06 +B.1. v06 to v07 + + o converted YANG module to YANG 1.1 + + o changed anyxml value to anydata value + + o updated import revision date for ietf-restconf + + o updated revision date for ietf-yang-patch because import-by- + revision date needed to be changed + +B.2. v05 to v06 o changed errors example so a full request and error response is shown in XML format o fixed error-path to match instance-identifier encoding for both XML and JSON o added references for YANG to JSON and YANG Metadata drafts o clarified that YANG JSON drafts are used for encoding, not plain JSON -B.2. v04 to v05 +B.3. v04 to v05 o updated reference to RESTCONF -B.3. v03 to v04 +B.4. v03 to v04 o removed NETCONF specific text - o changed data-resource-offset typedef from a relative URI to an XPath absolute path expression o clarified insert operation o removed requirement that edits MUST be applied in ascending order o change SHOULD keep datastore unchanged on error to MUST (this is required by HTTP PATCH) @@ -995,43 +995,43 @@ o removed requirement that edits MUST be applied in ascending order o change SHOULD keep datastore unchanged on error to MUST (this is required by HTTP PATCH) o removed length restriction on 'comment' leaf o updated YANG tree for example-jukebox library -B.4. v02 to v03 +B.5. v02 to v03 o added usage of restconf-media-type extension to map the yang-patch and yang-patch-status groupings to media types o added yang-patch RESTCONF capability URI o Added sub-section for terms used from RESTCONF o filled in security considerations section -B.5. v01 to v02 +B.6. v01 to v02 o Reversed order of change log o Clarified anyxml structure of "value" parameter within a YANG patch request (github issue #1) o Updated RESTCONF reference o Added note to open issues section to check github instead -B.6. v00 to v01 +B.7. v00 to v01 o Added text requiring support for Accept-Patch header, and removed 'Identification of YANG Patch capabilities' open issue. o Removed 'location' leaf from yang-patch-status grouping o Removed open issue 'Protocol independence' because the location leaf was removed. o Removed open issue 'RESTCONF coupling' because there is no concern @@ -1055,31 +1055,31 @@ o Removed open issue 'Bulk editing support in yang-patch-status'. The 'location' leaf has been removed so this issue is no longer applicable. o Removed open issue 'Edit list mechanism'. Added text to the 'edit' list description-stmt about how the individual edits must be processed. There is no concern about duplicate edits which cause intermediate results to be altered by subsequent edits in the same edit list. -B.7. bierman:yang-patch-00 to ietf:yang-patch-00 +B.8. bierman:yang-patch-00 to ietf:yang-patch-00 o Created open issues section Appendix C. Open Issues -- RFC Ed.: remove this section before publication. Refer to the github issue tracker for any open issues: - https://github.com/netconf-wg/yang-patch/issues + https://github.com/netconf-wg/yang-patch/issues [1] Appendix D. Example YANG Module The example YANG module used in this document represents a simple media jukebox interface. The "example-jukebox" YANG module is defined in [I-D.ietf-netconf-restconf]. YANG Tree Diagram for "example-jukebox" Module: +--rw jukebox!