--- 1/draft-ietf-netconf-yang-patch-05.txt 2015-10-18 13:16:43.012848810 -0700 +++ 2/draft-ietf-netconf-yang-patch-06.txt 2015-10-18 13:16:43.108851151 -0700 @@ -1,21 +1,21 @@ Network Working Group A. Bierman Internet-Draft YumaWorks Intended status: Standards Track M. Bjorklund -Expires: January 7, 2016 Tail-f Systems +Expires: April 20, 2016 Tail-f Systems K. Watsen Juniper Networks - July 6, 2015 + October 18, 2015 YANG Patch Media Type - draft-ietf-netconf-yang-patch-05 + draft-ietf-netconf-yang-patch-06 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 January 7, 2016. + This Internet-Draft will expire on April 20, 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 4 + 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5 1.1.5. YANG Patch . . . . . . . . . . . . . . . . . . . . . 5 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 - 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . 7 + 2.5. Edit Operations . . . . . . . . . . . . . . . . . . . . . 8 2.6. Error Handling . . . . . . . . . . . . . . . . . . . . . 8 - 2.7. yang-patch RESTCONF Capability . . . . . . . . . . . . . 8 - 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 - 4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 17 + 2.7. yang-patch RESTCONF Capability . . . . . . . . . . . . . 9 + 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 + 4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 18 4.2. application/yang.patch Media Types . . . . . . . . . . . 18 - 4.3. application/yang.patch-status Media Types . . . . . . . . 18 + 4.3. application/yang.patch-status Media Types . . . . . . . . 19 4.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 19 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19 - 6. Normative References . . . . . . . . . . . . . . . . . . . . 19 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 20 - Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 20 - B.1. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 20 - B.2. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 20 - B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 21 - B.4. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 21 - B.5. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 21 - B.6. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 22 - Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 22 - Appendix D. Example YANG Module . . . . . . . . . . . . . . . . 22 - D.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 23 - D.1.1. Add Resources: Error . . . . . . . . . . . . . . . . 23 - D.1.2. Add Resources: Success . . . . . . . . . . . . . . . 25 - D.1.3. Move list entry example . . . . . . . . . . . . . . . 27 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 + 6. Normative References . . . . . . . . . . . . . . . . . . . . 20 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 21 + 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 + 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 + 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. @@ -235,20 +238,27 @@ For RESTCONF, the YANG Patch operation is invoked by the client by sending a PATCH method request with the YANG Patch media type. A message body representing the YANG Patch input parameters MUST be provided. The RESTCONF server MUST return the Accept-Patch header in an OPTIONS response, as specified in [RFC5789], which includes the media type for YANG Patch. + A YANG Patch can be encoded in XML format according to + [W3C.REC-xml-20081126]. It can also be encoded in JSON, according to + "JSON Encoding of Data Modeled with YANG" + [I-D.ietf-netmod-yang-json]. If any meta-data needs to be sent in a + JSON message, it is encoded according to "Defining and Using Metadata + with YANG" [I-D.ietf-netmod-yang-metadata]. + Example: Accept-Patch: application/yang.patch 2.1. Target Resource The YANG Patch operation uses a conceptual root within a NETCONF configuration datastore to identity the patch point for the edit operation. This root can be the datastore itself, or 1 or more data nodes within the datastore. @@ -326,34 +335,36 @@ resource, then the path string in the "target" leaf is a relative path expression. The first node specified in the "target" leaf is a child node of the data node associated with the target resource. 2.5. Edit Operations Each YANG patch edit specifies one edit operation on the target data node. The set of operations is aligned with the NETCONF edit operations, but also includes some new operations. - +-----------+-------------------------------------------------------+ + +---------------+---------------------------------------------------+ | Operation | Description | - +-----------+-------------------------------------------------------+ + +---------------+---------------------------------------------------+ | create | create a new data resource if it does not already | | | exist or error | - | delete | delete a data resource if it already exists or error | + | delete | delete a data resource if it already exists or | + | | error | | insert | insert a new user-ordered data resource | - | merge | merge the edit value with the target data resource; | - | | create if it does not already exist | + | merge | merge the edit value with the target data | + | | resource; create if it does not already exist | | move | re-order the target data resource | - | replace | replace the target data resource with the edit value | + | replace | replace the target data resource with the edit | + | | value | | remove | remove a data resource if it already exists or no | | | error | - +-----------+-------------------------------------------------------+ + +---------------+---------------------------------------------------+ YANG Patch Edit Operations 2.6. Error Handling If a well-formed, schema-valid YANG Patch message is received, then the server will process the supplied edits in ascending order. The following error modes apply to the processing of this edit list: All the specified edits MUST be applied or the target datastore @@ -387,21 +398,21 @@ file "ietf-yang-patch@2015-04-30.yang" module ietf-yang-patch { 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-06-04; + revision-date 2015-10-07; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: WG List: WG Chair: Mehmet Ersue @@ -438,31 +449,30 @@ 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-04.txt + // Note: extracted from draft-ietf-netconf-yang-patch-06.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2015-06-04 { 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)."; } @@ -661,28 +671,32 @@ } anyxml 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. + 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: @@ -884,22 +897,32 @@ A server implementation SHOULD attempt to prevent system disruption due to partial processing of the YANG Patch edit list. It may be possible to construct an attack on such a server, which relies on the edit processing order mandated by YANG Patch. 6. Normative References [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF - Protocol", draft-ietf-netconf-restconf-07 (work in - progress), July 2015. + Protocol", draft-ietf-netconf-restconf-08 (work in + progress), October 2015. + + [I-D.ietf-netmod-yang-json] + Lhotka, L., "JSON Encoding of Data Modeled with YANG", + draft-ietf-netmod-yang-json-06 (work in progress), October + 2015. + + [I-D.ietf-netmod-yang-metadata] + Lhotka, L., "Defining and Using Metadata with YANG", + draft-ietf-netmod-yang-metadata-02 (work in progress), + September 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. @@ -923,71 +946,92 @@ and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- xml-20081126, November 2008, . Appendix A. Acknowledgements The authors would like to thank the following people for their contributions to this document: Rex Fernando. + Contributions to this material by Andy Bierman are based upon work + supported by the The Space & Terrestrial Communications Directorate + (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings + and conclusions or recommendations expressed in this material are + 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. 04 to 05 +B.1. 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 o updated reference to RESTCONF -B.2. 03 to 04 +B.3. 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) o removed length restriction on 'comment' leaf o updated YANG tree for example-jukebox library -B.3. 02 to 03 +B.4. 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.4. 01 to 02 +B.5. 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.5. 00 to 01 +B.6. 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 @@ -1011,21 +1055,21 @@ 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.6. bierman:yang-patch-00 to ietf:yang-patch-00 +B.7. 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 @@ -1077,86 +1121,121 @@ This section includes RESTCONF examples. Most examples are shown in JSON encoding [RFC7158], and some are shown in XML encoding [W3C.REC-xml-20081126]. D.1.1. Add Resources: Error The following example shows several songs being added to an existing album. Each edit contains one song. The first song already exists, so an error will be reported for that edit. The rest of the edits - were not attempted, since the first edit failed. + were not attempted, since the first edit failed. The XML encoding is + used in this example. Request from client: PATCH /restconf/data/example-jukebox:jukebox/ library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 + Host: example.com - Accept: application/yang.patch-status+json - Content-Type: application/yang.patch+json + Accept: application/yang.patch-status+xml + Content-Type: application/yang.patch+xml - { - "ietf-yang-patch:yang-patch" : { - "patch-id" : "add-songs-patch", - "edit" : [ - { - "edit-id" : "edit1", - "operation" : "create", - "target" : "/song", - "value" : { - "song" : { - "name" : "Bridge Burning", - "location" : "/media/bridge_burning.mp3", - "format" : "MP3", - "length" : 288 - } - } - }, - { - "edit-id" : "edit2", - "operation" : "create", - "target" : "/song", - "value" : { - "song" : { - "name" : "Rope", - "location" : "/media/rope.mp3", - "format" : "MP3", - "length" : 259 - } - } - }, - { - "edit-id" : "edit3", - "operation" : "create", - "target" : "/song", - "value" : { - "song" : { - "name" : "Dear Rosemary", - "location" : "/media/dear_rosemary.mp3", - "format" : "MP3", - "length" : 269 + + add-songs-patch + + edit1 + create + /song + + + Bridge Burning + /media/bridge_burning.mp3 + MP3 + 288 + + + + + edit2 + create + /song + + + Rope + /media/rope.mp3 + MP3 + 259 + + + + + edit3 + create + /song + + + Dear Rosemary + /media/dear_rosemary.mp3 + MP3 + 269 + + + + + XML Response from server: - } - } - } - ] - } - } + HTTP/1.1 409 Conflict + Date: Mon, 23 Apr 2012 13:01:20 GMT + Server: example-server + Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT + Content-Type: application/yang.patch-status+xml - Response from server: + + add-songs-patch + + + edit1 + + + application + data-exists + + /jb:jukebox/jb:library + /jb:artist[jb:name='Foo Fighters'] + /jb:album[jb:name='Wasting Light'] + /jb:song[jb:name='Burning Light'] + + + Data already exists, cannot be created + + + + + + + + JSON Response from server: + + The following response is shown in JSON format to highlight the + difference in the "error-path" object encoding. For JSON, the + instance-identifier encoding in the "JSON Encoding of YANG + Data" draft is used. The "error-path" string is wrapped for + display purposes. HTTP/1.1 409 Conflict Date: Mon, 23 Apr 2012 13:01:20 GMT Server: example-server Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Content-Type: application/yang.patch-status+json - { "ietf-yang-patch:yang-patch-status" : { "patch-id" : "add-songs-patch", "edit-status" : { "edit" : [ { "edit-id" : "edit1", "errors" : { "error" : [ { @@ -1156,22 +1235,23 @@ "edit-status" : { "edit" : [ { "edit-id" : "edit1", "errors" : { "error" : [ { "error-type": "application", "error-tag": "data-exists", "error-path": "/example-jukebox:jukebox/library - /artist=Foo%20Fighters/album=Wasting%20Light - /song=Burning%20Light", + /artist[name='Foo Fighters'] + /album[name='Wasting Light'] + /song[name='Burning Light']", "error-message": "Data already exists, cannot be created" } ] } } ] } } }