--- 1/draft-ietf-netconf-yang-patch-08.txt 2016-06-28 19:15:56.108779151 -0700 +++ 2/draft-ietf-netconf-yang-patch-09.txt 2016-06-28 19:15:56.176780851 -0700 @@ -1,21 +1,21 @@ Network Working Group A. Bierman Internet-Draft YumaWorks Intended status: Standards Track M. Bjorklund -Expires: September 17, 2016 Tail-f Systems +Expires: December 30, 2016 Tail-f Systems K. Watsen Juniper Networks - March 16, 2016 + June 28, 2016 YANG Patch Media Type - draft-ietf-netconf-yang-patch-08 + draft-ietf-netconf-yang-patch-09 Abstract This document describes a method for applying patches to configuration datastores using data defined with the YANG data modeling language. Status of This Memo This Internet-Draft is submitted in full conformance with the @@ -24,21 +24,21 @@ 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 September 17, 2016. + This Internet-Draft will expire on December 30, 2016. Copyright Notice Copyright (c) 2016 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 @@ -53,54 +53,55 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5 1.1.5. YANG Patch . . . . . . . . . . . . . . . . . . . . . 5 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1. Target Resource . . . . . . . . . . . . . . . . . . . . . 6 - 2.2. yang-patch Input . . . . . . . . . . . . . . . . . . . . 6 + 2.2. yang-patch Input . . . . . . . . . . . . . . . . . . . . 7 2.3. yang-patch-status Output . . . . . . . . . . . . . . . . 7 2.4. Target Data Node . . . . . . . . . . . . . . . . . . . . 8 2.5. Edit Operations . . . . . . . . . . . . . . . . . . . . . 8 2.6. Successful Edit Response Handling . . . . . . . . . . . . 9 2.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 9 2.8. 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 . . . . . . . . . . . 19 - 4.3. application/yang.patch-status Media Types . . . . . . . . 19 - 4.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 20 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 - 6. Normative References . . . . . . . . . . . . . . . . . . . . 20 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 21 - Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 22 - B.1. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 22 - B.2. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 22 - B.3. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 22 - B.4. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 23 - B.5. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 23 - B.6. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 23 - B.7. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 23 - B.8. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 24 - B.9. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 24 - - Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 25 - Appendix D. Example YANG Module . . . . . . . . . . . . . . . . 25 - D.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 26 - D.1.1. Add Resources: Error . . . . . . . . . . . . . . . . 26 - D.1.2. Add Resources: Success . . . . . . . . . . . . . . . 29 - D.1.3. Move list entry example . . . . . . . . . . . . . . . 30 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 + 4.2. Media Types . . . . . . . . . . . . . . . . . . . . . . . 19 + 4.2.1. Media Type application/yang-patch+xml . . . . . . . . 19 + 4.2.2. Media Type application/yang-patch+json . . . . . . . 20 + 4.3. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 22 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . 22 + 6. Normative References . . . . . . . . . . . . . . . . . . . . 23 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 24 + Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 24 + B.1. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . 25 + B.2. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 25 + B.3. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 25 + B.4. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 26 + B.5. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 26 + B.6. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 26 + B.7. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 26 + B.8. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 26 + B.9. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 27 + B.10. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 28 + Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 28 + Appendix D. Example YANG Module . . . . . . . . . . . . . . . . 28 + D.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 29 + D.1.1. Add Resources: Error . . . . . . . . . . . . . . . . 29 + D.1.2. Add Resources: Success . . . . . . . . . . . . . . . 32 + D.1.3. Move list entry example . . . . . . . . . . . . . . . 33 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 1. Introduction There is a need for standard mechanisms to patch datastores defined in [RFC6241], which contain conceptual data that conforms to schema specified with YANG [I-D.ietf-netmod-rfc6020bis]. An "ordered edit list" approach is needed to provide client developers with more precise client control of the edit procedure than existing mechanisms. @@ -137,40 +138,32 @@ o running configuration datastore o server o state data o user 1.1.2. HTTP - The following terms are defined in [RFC2616]: - - o entity tag - - o fragment + The following terms are defined in [RFC7230]: - o header line + o header field o message body o method - o path - o query o request URI - o response body - 1.1.3. YANG The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: o container o data node o key leaf @@ -174,56 +167,62 @@ o key leaf o leaf o leaf-list o list o presence container (or P-container) + o RPC operation (now called protocol operation) o non-presence container (or NP-container) o ordered-by system - o ordered-by user 1.1.4. RESTCONF The following terms are defined in [I-D.ietf-netconf-restconf]: + o application/yang-data+xml + + o application/yang-data+json + o data resource o datastore resource o patch o RESTCONF capability o target resource + o YANG data template + 1.1.5. YANG Patch The following terms are used within this document: o YANG Patch: a conceptual edit request using the "yang-patch" YANG - container, defined in Section 3. In HTTP, refers to a PATCH - method where the media type is "application/yang.patch+xml" or - "application/yang.patch+json". + data template, defined in Section 3. In HTTP, refers to a PATCH + method where a representation uses either the media type + "application/yang-patch+xml" or "application/yang-patch+json". o YANG Patch Status: a conceptual edit status response using the - YANG "yang-patch-status" container, defined in Section 3. In - HTTP, refers to a response message for a PATCH method, where the - message body is identified by the media type "application/ - yang.patch-status+xml" or "application/yang.patch-status+json". + YANG "yang-patch-status" YANG data template, defined in Section 3. + In HTTP, refers to a response message for a PATCH method, where it + has a representation with either the media type "application/ + yang-data+xml" or "application/yang-data+json". 1.1.6. Tree Diagrams A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration @@ -238,31 +237,32 @@ o Ellipsis ("...") stands for contents of subtrees that are not shown. 2. YANG Patch A "YANG Patch" is an ordered list of edits that are applied to the target datastore by the server. The specific fields are defined in the YANG module in Section 3. 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. + sending a PATCH method request with a representation using either the + "application/yang-patch+xml" or "application/yang-patch+json" 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. + The RESTCONF server MUST return the Accept-Patch header field in an + OPTIONS response, as specified in [RFC5789], which includes the media + type for YANG Patch. Example: - Accept-Patch: application/yang.patch + Accept-Patch: application/yang-patch+xml,application/yang-patch+json 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]. 2.1. Target Resource @@ -372,82 +373,74 @@ | 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. Successful Edit Response Handling - If a YANG Patch is completed without errors, the server MUST return a - "200 OK" status-line, and a response message-body containing a - "yang-patch-status" message. + If a YANG Patch is completed without errors, the server SHOULD return + a "yang-patch-status" message. The server will save the running datastore to non-volatile storage if it supports non-volatile storage, and if the running datastore contents have changed. This will be done in an implementation- specific manner. Refer to Appendix D.1.2 for a example of a successful YANG Patch response. 2.7. 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 - contents MUST be returned to its original state before the PATCH - method started. - - If a YANG Patch is completed with errors, the server MUST return a - "200 OK" status-line, and a response message-body containing a + If a YANG Patch is completed with errors, the server SHOULD return a "yang-patch-status" message. Refer to Appendix D.1.1 for a example of an error YANG Patch response. 2.8. yang-patch RESTCONF Capability A URI is defined to identify the YANG Patch extension to the base RESTCONF protocol. If the server supports the YANG Patch media type, - then the "yang-patch" RESTCONF capability defined in Section 4.4 MUST + then the "yang-patch" RESTCONF capability defined in Section 4.3 MUST be present in the "capability" leaf-list in the "ietf-restconf-monitoring" module defined in [I-D.ietf-netconf-restconf]. 3. YANG Module + The "ietf-yang-patch" module defines conceptual definitions with the - 'restconf-media-type' extension statements, which are not meant to be + 'yang-data' extension statements, which are not meant to be implemented as datastore contents by a server. The "ietf-restconf" module from [I-D.ietf-netconf-restconf] is used - by this module for the 'restconf-media-type' extension definition. + by this module for the 'yang-data' extension definition. RFC Ed.: update the date below with the date of RFC publication and remove this note. - file "ietf-yang-patch@2016-03-16.yang" + file "ietf-yang-patch@2016-06-28.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 2016-03-16; - } + import ietf-restconf { prefix rc; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: WG List: WG Chair: Mehmet Ersue @@ -483,50 +476,50 @@ 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-08.txt + // Note: extracted from draft-ietf-netconf-yang-patch-09.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. - revision 2016-03-16 { + revision 2016-06-28 { 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)."; } - rc:restconf-media-type "application/yang.patch" { + rc:yang-data "yang-patch" { uses yang-patch; } - rc:restconf-media-type "application/yang.patch-status" { + + rc:yang-data "yang-patch-status" { uses yang-patch-status; } grouping yang-patch { - description "A grouping that contains a YANG container representing the syntax and semantics of a YANG Patch edit request message."; container yang-patch { description "Represents a conceptual sequence of datastore edits, called a patch. Each patch is given a client-assigned patch identifier. Each edit MUST be applied @@ -834,81 +826,210 @@ } // grouping yang-patch-status } 4. IANA Considerations 4.1. YANG Module Registry - This document registers one URI in the IETF XML registry [RFC3688]. - Following the format in RFC 3688, the following registration is - requested to be made. + This document registers one URI as a namespace in the IETF XML + registry [RFC3688]. Following the format in RFC 3688, the following + registration is requested to be made. URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch Registrant Contact: The NETCONF WG of the IETF. XML: N/A, the requested URI is an XML namespace. This document registers one YANG module in the YANG Module Names registry [RFC6020]. name: ietf-yang-patch namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch prefix: ypatch // RFC Ed.: replace XXXX with RFC number and remove this note reference: RFC XXXX -4.2. application/yang.patch Media Types +4.2. Media Types - The MIME media type for a YANG Patch document is application/ - yang.patch. +4.2.1. Media Type application/yang-patch+xml Type name: application - Subtype name: yang.patch + Subtype name: yang-patch+xml Required parameters: none Optional parameters: none + // RFC Ed.: replace draft-ietf-netmod-rfc6020bis with + // the actual RFC reference for YANG 1.1, and remove this note. + + // RFC Ed.: replace 'XXXX' with the real RFC number, + // and remove this note + Encoding considerations: 8-bit + Each conceptual YANG data node is encoded according to + XML Encoding Rules and Canonical Format for the specific + YANG data node type defined in [draft-ietf-netmod-rfc6020bis]. + In addition, the "yang-patch" YANG data template found + in [RFCXXXX] defines the structure of a YANG Patch request. - Security considerations: See Section 5 of RFC XXXX + // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the + // section number for Security Considerations + // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual + // RFC number, and remove this note. - Interoperability considerations: none + Security considerations: Security considerations related + to the generation and consumption of RESTCONF messages + are discussed in Section NN of [RFCXXXX]. + Additional security considerations are specific to the + semantics of particular YANG data models. Each YANG module + is expected to specify security considerations for the + YANG data defined in that module. + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + + Interoperability considerations: [RFCXXXX] specifies format of + conforming messages and the interpretation thereof. + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. - // RFC Ed.: replace XXXX with RFC number and remove this note Published specification: RFC XXXX -4.3. application/yang.patch-status Media Types + Applications that use this media type: Instance document + data parsers used within a protocol or automation tool + that utilizes the YANG Patch data structure. - The MIME media type for a YANG Patch status document is application/ - yang.patch-status. + Fragment identifier considerations: The fragment field in the + request URI has no defined purpose. + + Additional information: + + Deprecated alias names for this type: n/a + Magic number(s): n/a + File extension(s): .xml + Macintosh file type code(s): "TEXT" + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + + Person & email address to contact for further information: See + Authors' Addresses section of [RFCXXXX]. + + Intended usage: COMMON + + (One of COMMON, LIMITED USE, or OBSOLETE.) + + Restrictions on usage: n/a + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + + Author: See Authors' Addresses section of [RFCXXXX]. + + Change controller: Internet Engineering Task Force + (mailto:iesg&ietf.org). + + Provisional registration? (standards tree only): no + +4.2.2. Media Type application/yang-patch+json Type name: application - Subtype name: yang.patch-status + Subtype name: yang-patch+json Required parameters: none - Optional parameters: none + // RFC Ed.: replace draft-ietf-netmod-yang-json with + // the actual RFC reference for JSON Encoding of YANG Data, + // and remove this note. + + // RFC Ed.: replace draft-ietf-netmod-yang-metadata with + // the actual RFC reference for JSON Encoding of YANG Data, + // and remove this note. + + // RFC Ed.: replace 'XXXX' with the real RFC number, + // and remove this note + Encoding considerations: 8-bit + Each conceptual YANG data node is encoded according to + [draft-ietf-netmod-yang-json]. A data annotation is + encoded according to [draft-ietf-netmod-yang-metadata] + In addition, the "yang-patch" YANG data template found + in [RFCXXXX] defines the structure of a YANG Patch request. - Security considerations: See Section 5 of RFC XXXX - Interoperability considerations: none + // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the + // section number for Security Considerations + // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual + // RFC number, and remove this note. + + Security considerations: Security considerations related + to the generation and consumption of RESTCONF messages + are discussed in Section NN of [RFCXXXX]. + Additional security considerations are specific to the + semantics of particular YANG data models. Each YANG module + is expected to specify security considerations for the + YANG data defined in that module. + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + + Interoperability considerations: [RFCXXXX] specifies format of + conforming messages and the interpretation thereof. + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. - // RFC Ed.: replace XXXX with RFC number and remove this note Published specification: RFC XXXX -4.4. RESTCONF Capability URNs + Applications that use this media type: Instance document + data parsers used within a protocol or automation tool + that utilizes the YANG Patch data structure. + + Fragment identifier considerations: The fragment field in the + request URI has no defined purpose. + + Additional information: + + Deprecated alias names for this type: n/a + Magic number(s): n/a + File extension(s): .json + Macintosh file type code(s): "TEXT" + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + + Person & email address to contact for further information: See + Authors' Addresses section of [RFCXXXX]. + + Intended usage: COMMON + + (One of COMMON, LIMITED USE, or OBSOLETE.) + + Restrictions on usage: n/a + + // RFC Ed.: replace XXXX with actual RFC number and remove this + // note. + + Author: See Authors' Addresses section of [RFCXXXX]. + + Change controller: Internet Engineering Task Force + (mailto:iesg&ietf.org). + + Provisional registration? (standards tree only): no + +4.3. RESTCONF Capability URNs This document registers one capability identifier in "RESTCONF Protocol Capability URNs" registry Index Capability Identifier ------------------------ :yang-patch urn:ietf:params:restconf:capability:yang-patch:1.0 @@ -931,70 +1053,74 @@ 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-08 (work in - progress), October 2015. + Protocol", draft-ietf-netconf-restconf-13 (work in + progress), April 2016. [I-D.ietf-netmod-rfc6020bis] Bjorklund, M., "The YANG 1.1 Data Modeling Language", draft-ietf-netmod-rfc6020bis-11 (work in progress), February 2016. [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. + draft-ietf-netmod-yang-json-10 (work in progress), March + 2016. [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. + draft-ietf-netmod-yang-metadata-07 (work in progress), + March 2016. [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. + DOI 10.17487/RFC3688, January 2004, + . [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010. [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. - [RFC7158] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data - Interchange Format", RFC 7158, March 2013. + [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data + Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March + 2014, . + + [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Message Syntax and Routing", RFC + 7230, DOI 10.17487/RFC7230, June 2014, + . [W3C.REC-xml-20081126] Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 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). @@ -998,107 +1124,123 @@ 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. v07 to v08 +B.1. v08 to v09 + + o change RFC 7158 reference to RFC 7159 reference + + o change RFC 2616 reference to RFC 7230 reference + + o remove unused HTTP terms + + o remove import-by-revision of ietf-restconf; not needed + + o change application/yang.patch media type to application/yang-patch + + o remove application/yang.patch-status media type; use application/ + yang-data instead + +B.2. v07 to v08 o clarified target datastore and target data node terms o clarified that target leaf can be single forward slash '/' o added Successful edit response handling section o clarified that YANG Patch draft is for RESTCONF protocol only but may be defined for other protocols outside this document o clarified that YANG Patch draft is for configuration datastores only but may be defined for other datastore types outside this document o fixed typos -B.2. v06 to v07 +B.3. 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.3. v05 to v06 +B.4. 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.4. v04 to v05 +B.5. v04 to v05 o updated reference to RESTCONF -B.5. v03 to v04 +B.6. 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.6. v02 to v03 +B.7. 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.7. v01 to v02 - +B.8. 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.8. v00 to v01 +B.9. v00 to v01 - o Added text requiring support for Accept-Patch header, and removed - 'Identification of YANG Patch capabilities' open issue. + o Added text requiring support for Accept-Patch header field, 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 about a normative reference to RESTCONF. There may need to be a YANG 1.1 mechanism to allow protocol template usage (instead of grouping wrapper). @@ -1119,21 +1261,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.9. bierman:yang-patch-00 to ietf:yang-patch-00 +B.10. 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 @@ -1177,38 +1319,38 @@ rpcs: +---x play +--ro input +--ro playlist string +--ro song-number uint32 D.1. YANG Patch Examples This section includes RESTCONF examples. Most examples are shown in - JSON encoding [RFC7158], and some are shown in XML encoding + JSON encoding [RFC7159], 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. 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+xml - Content-Type: application/yang.patch+xml + Accept: application/yang-data+xml + Content-Type: application/yang-patch+xml add-songs-patch edit1 create /song Bridge Burning @@ -1245,21 +1387,21 @@ 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 + Content-Type: application/yang-data+xml add-songs-patch edit1 application @@ -1286,21 +1428,21 @@ 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 + Content-Type: application/yang-data+json { "ietf-yang-patch:yang-patch-status" : { "patch-id" : "add-songs-patch", "edit-status" : { "edit" : [ { "edit-id" : "edit1", "errors" : { "error" : [ @@ -1330,22 +1473,22 @@ o Each of 2 edits contains one song. o Both edits succeed and new sub-resources are created 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-data+json + Content-Type: application/yang-patch+json { "ietf-yang-patch:yang-patch" : { "patch-id" : "add-songs-patch-2", "edit" : [ { "edit-id" : "edit1", "operation" : "create", "target" : "/song", "value" : { @@ -1374,43 +1517,43 @@ ] } } Response from server: HTTP/1.1 200 Success 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 + Content-Type: application/yang-data+json { "ietf-yang-patch:yang-patch-status" : { "patch-id" : "add-songs-patch-2", "ok" : [null] } } D.1.3. Move list entry example The following example shows a song being moved within an existing playlist. Song "1" in playlist "Foo-One" is being moved after song "3" in the playlist. The operation succeeds, so a non-error reply example can be shown. Request from client: PATCH /restconf/data/example-jukebox:jukebox/ playlist=Foo-One HTTP/1.1 Host: example.com - Accept: application/yang.patch-status+json - Content-Type: application/yang.patch+json + Accept: application/yang-patch+json + Content-Type: application/yang-data+json { "ietf-yang-patch:yang-patch" : { "patch-id" : "move-song-patch", "comment" : "Move song 1 after song 3", "edit" : [ { "edit-id" : "edit1", "operation" : "move", "target" : "/song/1", @@ -1409,33 +1552,33 @@ "ietf-yang-patch:yang-patch" : { "patch-id" : "move-song-patch", "comment" : "Move song 1 after song 3", "edit" : [ { "edit-id" : "edit1", "operation" : "move", "target" : "/song/1", "point" : "/song3", "where" : "after" + } ] } - } Response from server: HTTP/1.1 400 OK 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 + Content-Type: application/yang-data+json { "ietf-restconf:yang-patch-status" : { "patch-id" : "move-song-patch", "ok" : [null] } } Authors' Addresses