idnits 2.17.1 draft-ietf-netconf-yang-patch-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 376 has weird spacing: '...atch-id str...' == Line 380 has weird spacing: '...eration enu...' == Line 412 has weird spacing: '...edit-id str...' == Line 888 has weird spacing: '...eturned is 'o...' == Line 1465 has weird spacing: '...ocation str...' == (2 more instances...) -- The document date (November 22, 2016) is 2710 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 1118, but not defined ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: May 26, 2017 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 November 22, 2016 10 YANG Patch Media Type 11 draft-ietf-netconf-yang-patch-14 13 Abstract 15 This document describes a method for applying patches to 16 configuration datastores using data defined with the YANG data 17 modeling language. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on May 26, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5 59 1.1.5. YANG Patch . . . . . . . . . . . . . . . . . . . . . 5 60 1.1.6. Examples . . . . . . . . . . . . . . . . . . . . . . 5 61 1.1.7. Tree Diagram Notations . . . . . . . . . . . . . . . 6 62 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.1. Target Resource . . . . . . . . . . . . . . . . . . . . . 7 64 2.2. yang-patch Request . . . . . . . . . . . . . . . . . . . 8 65 2.3. yang-patch-status Response . . . . . . . . . . . . . . . 9 66 2.4. Target Data Node . . . . . . . . . . . . . . . . . . . . 10 67 2.5. Edit Operations . . . . . . . . . . . . . . . . . . . . . 11 68 2.6. Successful Edit Response Handling . . . . . . . . . . . . 11 69 2.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 11 70 2.8. yang-patch RESTCONF Capability . . . . . . . . . . . . . 12 71 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 73 4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 21 74 4.2. Media Types . . . . . . . . . . . . . . . . . . . . . . . 21 75 4.2.1. Media Type application/yang-patch+xml . . . . . . . . 21 76 4.2.2. Media Type application/yang-patch+json . . . . . . . 23 77 4.3. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 25 78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 25 79 6. Normative References . . . . . . . . . . . . . . . . . . . . 26 80 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 81 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 27 82 B.1. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . 27 83 B.2. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . 27 84 B.3. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . 28 85 B.4. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . 28 86 B.5. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . 28 87 B.6. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 29 88 B.7. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 29 89 B.8. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 29 90 B.9. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 29 91 B.10. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 30 92 B.11. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 30 93 B.12. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 30 94 B.13. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 30 95 B.14. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 31 97 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 31 98 Appendix D. Example YANG Module . . . . . . . . . . . . . . . . 31 99 D.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 32 100 D.1.1. Add Resources: Error . . . . . . . . . . . . . . . . 32 101 D.1.2. Add Resources: Success . . . . . . . . . . . . . . . 36 102 D.1.3. Insert list entry example . . . . . . . . . . . . . . 38 103 D.1.4. Move list entry example . . . . . . . . . . . . . . . 40 104 D.1.5. Edit datastore resource example . . . . . . . . . . . 41 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 107 1. Introduction 109 There is a need for standard mechanisms to patch datastores defined 110 in [RFC6241], which contain conceptual data that conforms to schema 111 specified with YANG [RFC7950]. An "ordered edit list" approach is 112 needed to provide RESTCONF client developers with more precise 113 RESTCONF client control of the edit procedure than existing 114 mechanisms found in [I-D.ietf-netconf-restconf]. 116 This document defines a media type for a YANG-based editing mechanism 117 that can be used with the HTTP PATCH method [RFC5789]. YANG Patch is 118 designed to support the RESTCONF protocol, defined in 119 [I-D.ietf-netconf-restconf]. This document only specifies the use of 120 the YANG Patch media type with the RESTCONF protocol. 122 It may be possible to use YANG Patch with other protocols besides 123 RESTCONF. This is outside the scope of this document. For any 124 protocol which supports the YANG Patch media type, if the entire 125 patch document cannot be successfully applied, then the server MUST 126 NOT apply any of the changes. It may be possible to use YANG Patch 127 with datastore types other than a configuration datastore. This is 128 outside the scope of this document. 130 1.1. Terminology 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 134 document are to be interpreted as described in [RFC2119]. 136 1.1.1. NETCONF 138 The following terms are defined in [RFC6241]: 140 o configuration data 142 o datastore 144 o configuration datastore 145 o protocol operation 147 o running configuration datastore 149 o state data 151 o user 153 1.1.2. HTTP 155 The following terms are defined in [RFC7230]: 157 o header field 159 o message-body 161 o query 163 o request URI 165 The following terms are defined in [RFC7231]: 167 o method 169 o request 171 o resource 173 1.1.3. YANG 175 The following terms are defined in [RFC7950]: 177 o container 179 o data node 181 o leaf 183 o leaf-list 185 o list 187 o RPC operation (now called protocol operation) 189 1.1.4. RESTCONF 191 The following terms are defined in [I-D.ietf-netconf-restconf]: 193 o application/yang-data+xml 195 o application/yang-data+json 197 o data resource 199 o datastore resource 201 o patch 203 o RESTCONF capability 205 o target resource 207 o YANG data template 209 1.1.5. YANG Patch 211 The following terms are used within this document: 213 o RESTCONF client: a client which implements the RESTCONF protocol. 215 o RESTCONF server: a server which implements the RESTCONF protocol. 217 o YANG Patch: a conceptual edit request using the "yang-patch" YANG 218 Patch template, defined in Section 3. In HTTP, refers to a PATCH 219 method where a representation uses either the media type 220 "application/yang-patch+xml" or "application/yang-patch+json". 222 o YANG Patch Status: a conceptual edit status response using the 223 YANG "yang-patch-status" YANG data template, defined in Section 3. 224 In HTTP, refers to a response message for a PATCH method, where it 225 has a representation with either the media type "application/ 226 yang-data+xml" or "application/yang-data+json". 228 o YANG Patch template: this is similar to a YANG data template, 229 except it has a representation with the media type "application/ 230 yang-patch+xml" or "application/yang-patch+json". 232 1.1.6. Examples 234 Some protocol message lines within examples throughout the document 235 are split into multiple lines for display purposes only. When a line 236 ends with backslash ('\') as the last character, the line is wrapped 237 for display purposes. It is to be considered to be joined to the 238 next line by deleting the backslash, the following line break, and 239 the leading whitespace of the next line. 241 1.1.7. Tree Diagram Notations 243 A simplified graphical representation of the data model is used in 244 this document. The meaning of the symbols in these diagrams is as 245 follows: 247 o Brackets "[" and "]" enclose list keys. 249 o Abbreviations before data node names: "rw" means configuration 250 data (read-write), "ro" state data (read-only), and "x" operation 251 resource (executable) 253 o Symbols after data node names: "?" means an optional node and "*" 254 denotes a "list" and "leaf-list". 256 o Parentheses enclose choice and case nodes, and case nodes are also 257 marked with a colon (":"). 259 o Ellipsis ("...") stands for contents of subtrees that are not 260 shown. 262 2. YANG Patch 264 A "YANG Patch" is an ordered list of edits that are applied to the 265 target datastore by the RESTCONF server. The specific fields are 266 defined in the YANG module in Section 3. 268 The YANG Patch operation is invoked by the RESTCONF client by sending 269 a PATCH method request with a representation using either the 270 "application/yang-patch+xml" or "application/yang-patch+json" media 271 type. This message-body representing the YANG Patch input parameters 272 MUST be present. 274 YANG Patch has some features that are not possible with the PATCH 275 method in RESTCONF: 277 o YANG Patch allows multiple sub-resources to be edited within the 278 same PATCH method. 280 o YANG Patch allows more precise edit operations than RESTCONF. 281 There are 7 operations supported (create, delete, insert, merge, 282 move, replace, remove). 284 o YANG Patch uses an edit list with an explicit processing order. 285 The edits are processed in client-specified order, and error 286 processing can be precise even when multiple errors occur in the 287 same patch request. 289 The YANG Patch "patch-id" may be useful for debugging, and SHOULD be 290 present in any audit audit logging records generated by the RESTCONF 291 server for a patch. 293 The RESTCONF server MUST return the Accept-Patch header field in an 294 OPTIONS response, as specified in [RFC5789], which includes the media 295 type for YANG Patch. This is needed by a client to determine the 296 message encoding formats supported by the server (e.g., XML, JSON, or 297 both). An example is shown in Figure 1. 299 Accept-Patch: application/yang-patch+xml,application/yang-patch+json 301 Figure 1: Example Accept-Patch header 303 Note that YANG Patch can only edit data resources. The PATCH method 304 cannot be used to replace the datastore resource. Although the 305 "ietf-yang-patch" YANG module is written using YANG version 1.1 306 [RFC7950], an implementation of YANG Patch can be used with content 307 defined in YANG version 1 [RFC6020] as well. 309 A YANG Patch can be encoded in XML format according to 310 [W3C.REC-xml-20081126]. It can also be encoded in JSON, according to 311 "JSON Encoding of Data Modeled with YANG" [RFC7951]. If any meta- 312 data needs to be sent in a JSON message, it is encoded according to 313 "Defining and Using Metadata with YANG" [RFC7952]. 315 2.1. Target Resource 317 The YANG Patch operation uses the RESTCONF target resource URI to 318 identify the resource that will be patched. This can be the 319 datastore resource itself, i.e., "{+restconf}/data", to edit top- 320 level configuration data resources, or it can be a configuration data 321 resource within the datastore resource, e.g., "{+restconf}/data/ 322 ietf-interfaces:interfaces", to edit sub-resources within a top-level 323 configuration data resource. 325 The target resource MUST identify exactly one resource instance. If 326 more than one resource instance is identified, then the request MUST 327 NOT be processed, and a "400 Bad Request" error response MUST be sent 328 by the server. If the target resource does not identify any existing 329 resource instance then the request MUST NOT be processed, and a "404 330 Not Found" error response MUST be sent by the server. 332 Each edit with a YANG Patch identifies a target data node for the 333 associated edit. This is described in Section 2.4. 335 2.2. yang-patch Request 337 A YANG patch is optionally identified by a unique "patch-id" and it 338 may have an optional comment. A patch is an ordered collection of 339 edits. Each edit is identified by an "edit-id" and it has an edit 340 operation (create, delete, insert, merge, move, replace, remove) that 341 is applied to the target resource. Each edit can be applied to a 342 sub-resource "target" within the target resource. If the operation 343 is "insert" or "move", then the "where" parameter indicates how the 344 node is inserted or moved. For values "before" and "after", the 345 "point" parameter specifies the data node insertion point. 347 The merge, replace, create, delete, and remove edit operations have 348 the exact same meaning as defined for the "operation" attribute in 349 section 7.2 of [RFC6241]. 351 Each edit within a YANG Patch MUST identify exactly one data resource 352 instance. If an edit represents more than one resource instance, 353 then the request MUST NOT be processed, and a "400 Bad Request" error 354 response MUST be sent by the server. If the edit does not identify 355 any existing resource instance, and the operation for the edit is not 356 "create", then the request MUST NOT be processed, and a "404 Not 357 Found" error response MUST be sent by the server. A 358 "yang-patch-status" response MUST be sent by the server identifying 359 the edit(s) that are not valid. 361 YANG Patch does not provide any access to specific datastores. It is 362 an implementation detail how a server processes an edit if it is co- 363 located with a NETCONF server that does provide access to individual 364 datastores. A complete datastore cannot be replaced in the same 365 manner as provided by the "copy-config" operation defined in section 366 7.3 of [RFC6241]. Only the specified nodes in a YANG Patch are 367 affected. 369 A message-body representing the YANG Patch is sent by the RESTCONF 370 client to specify the edit operation request. When used with the 371 HTTP PATCH method, this data is identified by the YANG Patch media 372 type. 374 YANG tree diagram for "yang-patch" Container 375 +---- yang-patch 376 +---- patch-id string 377 +---- comment? string 378 +---- edit* [edit-id] 379 +---- edit-id string 380 +---- operation enumeration 381 +---- target target-resource-offset 382 +---- point? target-resource-offset 383 +---- where? enumeration 384 +---- value? 386 2.3. yang-patch-status Response 388 A message-body representing the YANG Patch Status is returned to the 389 RESTCONF client to report the detailed status of the edit operation. 390 When used with the HTTP PATCH method, this data is identified by the 391 YANG Patch Status media type, and the syntax specification is defined 392 in Section 3. 394 YANG tree diagram for "yang-patch-status" Container: 396 +---- yang-patch-status 397 +---- patch-id string 398 +---- (global-status)? 399 | +--:(global-errors) 400 | | +---- errors 401 | | +---- error* 402 | | +---- error-type enumeration 403 | | +---- error-tag string 404 | | +---- error-app-tag? string 405 | | +---- error-path? instance-identifier 406 | | +---- error-message? string 407 | | +---- error-info? 408 | +--:(ok) 409 | +---- ok? empty 410 +---- edit-status 411 +---- edit* [edit-id] 412 +---- edit-id string 413 +---- (edit-status-choice)? 414 +--:(ok) 415 | +---- ok? empty 416 +--:(errors) 417 +---- errors 418 +---- error* 419 +---- error-type enumeration 420 +---- error-tag string 421 +---- error-app-tag? string 422 +---- error-path? instance-identifier 423 +---- error-message? string 424 +---- error-info? 426 2.4. Target Data Node 428 The target data node for each edit operation is determined by the 429 value of the target resource in the request and the "target" leaf 430 within each "edit" entry. 432 If the target resource specified in the request URI identifies a 433 datastore resource, then the path string in the "target" leaf is 434 treated as an absolute path expression identifying the target data 435 node for the corresponding edit. The first node specified in the 436 "target" leaf is a top-level data node defined within a YANG module. 437 The "target" leaf MUST NOT contain a single forward slash "/", since 438 this would identify the datastore resource, not a data resource. 440 If the target resource specified in the request URI identifies a 441 configuration data resource, then the path string in the "target" 442 leaf is treated as a relative path expression. The first node 443 specified in the "target" leaf is a child configuration data node of 444 the data node associated with the target resource. If the "target" 445 leaf contains a single forward slash "/", then the target data node 446 is the target resource data node. 448 2.5. Edit Operations 450 Each YANG patch edit specifies one edit operation on the target data 451 node. The set of operations is aligned with the NETCONF edit 452 operations, but also includes some new operations. 454 +-----------+-------------------------------------------------------+ 455 | Operation | Description | 456 +-----------+-------------------------------------------------------+ 457 | create | create a new data resource if it does not already | 458 | | exist or error | 459 | delete | delete a data resource if it already exists or error | 460 | insert | insert a new user-ordered data resource | 461 | merge | merge the edit value with the target data resource; | 462 | | create if it does not already exist | 463 | move | re-order the target data resource | 464 | replace | replace the target data resource with the edit value | 465 | remove | remove a data resource if it already exists | 466 +-----------+-------------------------------------------------------+ 468 YANG Patch Edit Operations 470 2.6. Successful Edit Response Handling 472 If a YANG Patch is completed without errors, the RESTCONF server MUST 473 return a "yang-patch-status" message with a global-status choice set 474 to 'ok'. 476 The RESTCONF server will save the running datastore to non-volatile 477 storage if it supports non-volatile storage, and if the running 478 datastore contents have changed, as specified in 479 [I-D.ietf-netconf-restconf]. 481 Refer to Appendix D.1.2 for a example of a successful YANG Patch 482 response. 484 2.7. Error Handling 486 If a well-formed, schema-valid YANG Patch message is received, then 487 the RESTCONF server will process the supplied edits in ascending 488 order. The following error modes apply to the processing of this 489 edit list: 491 If a YANG Patch is completed with errors, the RESTCONF server SHOULD 492 return a "yang-patch-status" message. It is possible (e.g., within a 493 distributed implementation), that an invalid request will be rejected 494 before the YANG patch edits are processed. In this case, the server 495 MUST send the appropriate HTTP error response instead. 497 Refer to Appendix D.1.1 for a example of an error YANG Patch 498 response. 500 2.8. yang-patch RESTCONF Capability 502 A URI is defined to identify the YANG Patch extension to the base 503 RESTCONF protocol. If the RESTCONF server supports the YANG Patch 504 media type, then the "yang-patch" RESTCONF capability defined in 505 Section 4.3 MUST be present in the "capability" leaf-list in the 506 "ietf-restconf-monitoring" module defined in 507 [I-D.ietf-netconf-restconf]. 509 3. YANG Module 511 The "ietf-yang-patch" module defines conceptual definitions with the 512 'yang-data' extension statements, which are not meant to be 513 implemented as datastore contents by a RESTCONF server. 515 The "ietf-restconf" module from [I-D.ietf-netconf-restconf] is used 516 by this module for the 'yang-data' extension definition. 518 RFC Ed.: update the date below with the date of RFC publication and 519 remove this note. 521 file "ietf-yang-patch@2016-11-09.yang" 523 module ietf-yang-patch { 524 yang-version 1.1; 525 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch"; 526 prefix "ypatch"; 528 import ietf-restconf { prefix rc; } 530 organization 531 "IETF NETCONF (Network Configuration) Working Group"; 533 contact 534 "WG Web: 535 WG List: 537 Author: Andy Bierman 538 540 Author: Martin Bjorklund 541 543 Author: Kent Watsen 544 "; 546 description 547 "This module contains conceptual YANG specifications 548 for the YANG Patch and YANG Patch Status data structures. 550 Note that the YANG definitions within this module do not 551 represent configuration data of any kind. 552 The YANG grouping statements provide a normative syntax 553 for XML and JSON message encoding purposes. 555 Copyright (c) 2016 IETF Trust and the persons identified as 556 authors of the code. All rights reserved. 558 Redistribution and use in source and binary forms, with or 559 without modification, is permitted pursuant to, and subject 560 to the license terms contained in, the Simplified BSD License 561 set forth in Section 4.c of the IETF Trust's Legal Provisions 562 Relating to IETF Documents 563 (http://trustee.ietf.org/license-info). 565 This version of this YANG module is part of RFC XXXX; see 566 the RFC itself for full legal notices."; 568 // RFC Ed.: replace XXXX with actual RFC number and remove this 569 // note. 571 // RFC Ed.: remove this note 572 // Note: extracted from draft-ietf-netconf-yang-patch-14.txt 574 // RFC Ed.: update the date below with the date of RFC publication 575 // and remove this note. 576 revision 2016-11-09 { 577 description 578 "Initial revision."; 579 reference 580 "RFC XXXX: YANG Patch Media Type."; 581 } 583 typedef target-resource-offset { 584 type string; 585 description 586 "Contains a data resource identifier string representing 587 a sub-resource within the target resource. 589 The document root for this expression is the 590 target resource that is specified in the 591 protocol operation (e.g., the URI for the PATCH request). 593 This string is encoded according the same rules as 594 a data resource identifier in a RESTCONF Request URI."; 596 // RFC Ed.: replace "draft-ietf-netconf-restconf" below 597 // with RFC XXXX, where XXXX is the number of the RESTCONF RFC, 598 // and remove this note. 600 reference 601 "draft-ietf-netconf-restconf, section 3.5.3"; 602 } 604 rc:yang-data "yang-patch" { 605 uses yang-patch; 606 } 608 rc:yang-data "yang-patch-status" { 609 uses yang-patch-status; 610 } 612 grouping yang-patch { 614 description 615 "A grouping that contains a YANG container 616 representing the syntax and semantics of a 617 YANG Patch edit request message."; 619 container yang-patch { 620 description 621 "Represents a conceptual sequence of datastore edits, 622 called a patch. Each patch is given a client-assigned 623 patch identifier. Each edit MUST be applied 624 in ascending order, and all edits MUST be applied. 625 If any errors occur, then the target datastore MUST NOT 626 be changed by the patch operation. 628 YANG datastore validation is performed before any edits 629 have been applied to the running datastore. 631 It is possible for a datastore constraint violation to occur 632 due to any node in the datastore, including nodes not 633 included in the edit list. Any validation errors MUST 634 be reported in the reply message."; 636 reference 637 "RFC 7950, section 8.3."; 639 leaf patch-id { 640 type string; 641 mandatory true; 642 description 643 "An arbitrary string provided by the client to identify 644 the entire patch. Error messages returned by the server 645 pertaining to this patch will be identified by this 646 patch-id value. A client SHOULD attempt to generate 647 unique patch-id values to distinguish between transactions 648 from multiple clients in any audit logs maintained 649 by the server."; 650 } 652 leaf comment { 653 type string; 654 description 655 "An arbitrary string provided by the client to describe 656 the entire patch. This value SHOULD be present in any 657 audit logging records generated by the server for the 658 patch."; 659 } 661 list edit { 662 key edit-id; 663 ordered-by user; 665 description 666 "Represents one edit within the YANG Patch 667 request message. The edit list is applied 668 in the following manner: 670 - The first edit is conceptually applied to a copy 671 of the existing target datastore, e.g., the 672 running configuration datastore. 673 - Each ascending edit is conceptually applied to 674 the result of the previous edit(s). 675 - After all edits have been successfully processed, 676 the result is validated according to YANG constraints. 677 - If successful, the server will attempt to apply 678 the result to the target datastore. "; 680 leaf edit-id { 681 type string; 682 description 683 "Arbitrary string index for the edit. 684 Error messages returned by the server pertaining 685 to a specific edit will be identified by this 686 value."; 687 } 689 leaf operation { 690 type enumeration { 691 enum create { 692 description 693 "The target data node is created using the supplied 694 value, only if it does not already exist. The 695 'target' leaf identifies the data node to be created, 696 not the parent data node."; 697 } 698 enum delete { 699 description 700 "Delete the target node, only if the data resource 701 currently exists, otherwise return an error."; 702 } 703 enum insert { 704 description 705 "Insert the supplied value into a user-ordered 706 list or leaf-list entry. The target node must 707 represent a new data resource. If the 'where' 708 parameter is set to 'before' or 'after', then 709 the 'point' parameter identifies the insertion 710 point for the target node."; 711 } 712 enum merge { 713 description 714 "The supplied value is merged with the target data 715 node."; 716 } 717 enum move { 718 description 719 "Move the target node. Reorder a user-ordered 720 list or leaf-list. The target node must represent 721 an existing data resource. If the 'where' parameter 722 is set to 'before' or 'after', then the 'point' 723 parameter identifies the insertion point to move 724 the target node."; 725 } 726 enum replace { 727 description 728 "The supplied value is used to replace the target 729 data node."; 730 } 731 enum remove { 732 description 733 "Delete the target node if it currently exists."; 734 } 735 } 736 mandatory true; 737 description 738 "The datastore operation requested for the associated 739 edit entry"; 740 } 742 leaf target { 743 type target-resource-offset; 744 mandatory true; 745 description 746 "Identifies the target data node for the edit 747 operation. If the target has the value '/', then 748 the target data node is the target resource. 749 The target node MUST identify a data resource, 750 not the datastore resource."; 751 } 753 leaf point { 754 when "(../operation = 'insert' or ../operation = 'move') " 755 + "and (../where = 'before' or ../where = 'after')" { 756 description 757 "Point leaf only applies for insert or move 758 operations, before or after an existing entry."; 759 } 760 type target-resource-offset; 761 description 762 "The absolute URL path for the data node that is being 763 used as the insertion point or move point for the 764 target of this edit entry."; 765 } 767 leaf where { 768 when "../operation = 'insert' or ../operation = 'move'" { 769 description 770 "Where leaf only applies for insert or move 771 operations."; 772 } 773 type enumeration { 774 enum before { 775 description 776 "Insert or move a data node before the data resource 777 identified by the 'point' parameter."; 778 } 779 enum after { 780 description 781 "Insert or move a data node after the data resource 782 identified by the 'point' parameter."; 783 } 784 enum first { 785 description 786 "Insert or move a data node so it becomes ordered 787 as the first entry."; 788 } 789 enum last { 790 description 791 "Insert or move a data node so it becomes ordered 792 as the last entry."; 793 } 794 } 795 default last; 796 description 797 "Identifies where a data resource will be inserted or 798 moved. YANG only allows these operations for 799 list and leaf-list data nodes that are ordered-by 800 user."; 801 } 803 anydata value { 804 when "../operation = 'create' " 805 + "or ../operation = 'merge' " 806 + "or ../operation = 'replace' " 807 + "or ../operation = 'insert'" { 808 description 809 "Value node only used for create, merge, 810 replace, and insert operations"; 811 } 812 description 813 "Value used for this edit operation. The anydata 'value' 814 contains the target resource associated with the 815 'target' leaf. 817 For example, suppose the target node is a YANG container 818 named foo: 820 container foo { 821 leaf a { type string; } 822 leaf b { type int32; } 823 } 825 The 'value' node contains one instance of foo: 827 828 829 some value 830 42 831 832 833 "; 834 } 835 } 836 } 838 } // grouping yang-patch 840 grouping yang-patch-status { 842 description 843 "A grouping that contains a YANG container 844 representing the syntax and semantics of 845 YANG Patch status response message."; 847 container yang-patch-status { 848 description 849 "A container representing the response message 850 sent by the server after a YANG Patch edit 851 request message has been processed."; 853 leaf patch-id { 854 type string; 855 description 856 "The patch-id value used in the request. 857 If there was no patch-id present in the request 858 then this field will not be present."; 859 } 861 choice global-status { 862 description 863 "Report global errors or complete success. 864 If there is no case selected then errors 865 are reported in the edit-status container."; 867 case global-errors { 868 uses rc:errors; 869 description 870 "This container will be present if global 871 errors that are unrelated to a specific edit 872 occurred."; 873 } 874 leaf ok { 875 type empty; 876 description 877 "This leaf will be present if the request succeeded 878 and there are no errors reported in the edit-status 879 container."; 880 } 881 } 883 container edit-status { 884 description 885 "This container will be present if there are 886 edit-specific status responses to report. 887 If all edits succeeded and the 'global-status' 888 returned is 'ok', then a server MAY omit this 889 container"; 891 list edit { 892 key edit-id; 894 description 895 "Represents a list of status responses, 896 corresponding to edits in the YANG Patch 897 request message. If an edit entry was 898 skipped or not reached by the server, 899 then this list will not contain a corresponding 900 entry for that edit."; 902 leaf edit-id { 903 type string; 904 description 905 "Response status is for the edit list entry 906 with this edit-id value."; 907 } 908 choice edit-status-choice { 909 description 910 "A choice between different types of status 911 responses for each edit entry."; 912 leaf ok { 913 type empty; 914 description 915 "This edit entry was invoked without any 916 errors detected by the server associated 917 with this edit."; 918 } 919 case errors { 920 uses rc:errors; 921 description 922 "The server detected errors associated with the 923 edit identified by the same edit-id value."; 925 } 926 } 927 } 928 } 929 } 930 } // grouping yang-patch-status 932 } 934 936 4. IANA Considerations 938 4.1. YANG Module Registry 940 This document registers one URI as a namespace in the IETF XML 941 registry [RFC3688]. Following the format in RFC 3688, the following 942 registration is requested to be made. 944 URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch 945 Registrant Contact: The NETCONF WG of the IETF. 946 XML: N/A, the requested URI is an XML namespace. 948 This document registers one YANG module in the YANG Module Names 949 registry [RFC6020]. 951 name: ietf-yang-patch 952 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch 953 prefix: ypatch 954 // RFC Ed.: replace XXXX with RFC number and remove this note 955 reference: RFC XXXX 957 4.2. Media Types 959 4.2.1. Media Type application/yang-patch+xml 961 Type name: application 963 Subtype name: yang-patch+xml 965 Required parameters: None 967 Optional parameters: None 969 // RFC Ed.: replace 'XXXX' with the real RFC number, 970 // and remove this note 972 Encoding considerations: 8-bit 973 The utf-8 charset is always used for this type. 974 Each conceptual YANG data node is encoded according to the 975 XML Encoding Rules and Canonical Format for the specific 976 YANG data node type defined in [RFC7950]. 977 In addition, the "yang-patch" YANG Patch template found 978 in [RFCXXXX] defines the structure of a YANG Patch request. 980 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 981 // section number for Security Considerations 982 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 983 // RFC number, and remove this note. 985 Security considerations: Security considerations related 986 to the generation and consumption of RESTCONF messages 987 are discussed in Section NN of [RFCXXXX]. 988 Additional security considerations are specific to the 989 semantics of particular YANG data models. Each YANG module 990 is expected to specify security considerations for the 991 YANG data defined in that module. 993 // RFC Ed.: replace XXXX with actual RFC number and remove this 994 // note. 996 Interoperability considerations: [RFCXXXX] specifies the format 997 of conforming messages and the interpretation thereof. 999 // RFC Ed.: replace XXXX with actual RFC number and remove this 1000 // note. 1002 Published specification: RFC XXXX 1004 Applications that use this media type: Instance document 1005 data parsers used within a protocol or automation tool 1006 that utilize the YANG Patch data structure. 1008 Fragment identifier considerations: Same as for application/xml 1010 Additional information: 1012 Deprecated alias names for this type: N/A 1013 Magic number(s): N/A 1014 File extension(s): None 1015 Macintosh file type code(s): "TEXT" 1017 // RFC Ed.: replace XXXX with actual RFC number and remove this 1018 // note. 1020 Person & email address to contact for further information: See 1021 Authors' Addresses section of [RFCXXXX]. 1023 Intended usage: COMMON 1025 Restrictions on usage: N/A 1027 // RFC Ed.: replace XXXX with actual RFC number and remove this 1028 // note. 1030 Author: See Authors' Addresses section of [RFCXXXX]. 1032 Change controller: Internet Engineering Task Force 1033 (mailto:iesg&ietf.org). 1035 Provisional registration? (standards tree only): no 1037 4.2.2. Media Type application/yang-patch+json 1039 Type name: application 1041 Subtype name: yang-patch+json 1043 Required parameters: None 1045 Optional parameters: None 1047 // RFC Ed.: replace draft-ietf-netmod-yang-json with 1048 // the actual RFC reference for JSON Encoding of YANG Data, 1049 // and remove this note. 1051 // RFC Ed.: replace draft-ietf-netmod-yang-metadata with 1052 // the actual RFC reference for JSON Encoding of YANG Data, 1053 // and remove this note. 1055 // RFC Ed.: replace 'XXXX' with the real RFC number, 1056 // and remove this note 1058 Encoding considerations: 8-bit 1059 The utf-8 charset is always used for this type. 1060 Each conceptual YANG data node is encoded according to 1061 [draft-ietf-netmod-yang-json]. A data annotation is 1062 encoded according to [draft-ietf-netmod-yang-metadata] 1063 In addition, the "yang-patch" YANG Patch template found 1064 in [RFCXXXX] defines the structure of a YANG Patch request. 1066 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 1067 // section number for Security Considerations 1068 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 1069 // RFC number, and remove this note. 1071 Security considerations: Security considerations related 1072 to the generation and consumption of RESTCONF messages 1073 are discussed in Section NN of [RFCXXXX]. 1074 Additional security considerations are specific to the 1075 semantics of particular YANG data models. Each YANG module 1076 is expected to specify security considerations for the 1077 YANG data defined in that module. 1079 // RFC Ed.: replace XXXX with actual RFC number and remove this 1080 // note. 1082 Interoperability considerations: [RFCXXXX] specifies the format 1083 of conforming messages and the interpretation thereof. 1085 // RFC Ed.: replace XXXX with actual RFC number and remove this 1086 // note. 1088 Published specification: RFC XXXX 1090 Applications that use this media type: Instance document 1091 data parsers used within a protocol or automation tool 1092 that utilize the YANG Patch data structure. 1094 Fragment identifier considerations: The syntax and semantics 1095 of fragment identifiers are the same as specified for the 1096 "application/json" media type. 1098 Additional information: 1100 Deprecated alias names for this type: N/A 1101 Magic number(s): N/A 1102 File extension(s): None 1103 Macintosh file type code(s): "TEXT" 1105 // RFC Ed.: replace XXXX with actual RFC number and remove this 1106 // note. 1108 Person & email address to contact for further information: See 1109 Authors' Addresses section of [RFCXXXX]. 1111 Intended usage: COMMON 1113 Restrictions on usage: N/A 1115 // RFC Ed.: replace XXXX with actual RFC number and remove this 1116 // note. 1118 Author: See Authors' Addresses section of [RFCXXXX]. 1120 Change controller: Internet Engineering Task Force 1121 (mailto:iesg&ietf.org). 1123 Provisional registration? (standards tree only): no 1125 4.3. RESTCONF Capability URNs 1127 This document registers one capability identifier in "RESTCONF 1128 Protocol Capability URNs" registry 1130 Index 1131 Capability Identifier 1132 ------------------------ 1134 :yang-patch 1135 urn:ietf:params:restconf:capability:yang-patch:1.0 1137 5. Security Considerations 1139 The YANG Patch media type does not introduce any significant new 1140 security threats, beyond what is described in 1141 [I-D.ietf-netconf-restconf]. This document defines edit processing 1142 instructions for a variant of the PATCH method, as used within the 1143 RESTCONF protocol. Message integrity is provided by the RESTCONF 1144 protocol. There is no additional capability to validate that a patch 1145 has not been altered. 1147 It may be possible to use YANG Patch with other protocols besides 1148 RESTCONF, which is outside the scope of this document. 1150 For RESTCONF, both the client and server MUST be authenticated, 1151 according to section 2 of [I-D.ietf-netconf-restconf]. It is 1152 important for RESTCONF server implementations to carefully validate 1153 all the edit request parameters in some manner. If the entire YANG 1154 Patch request cannot be completed, then no configuration changes to 1155 the system are done. A PATCH request MUST be applied atomically, as 1156 specified in section 2 of [RFC5789]. 1158 A RESTCONF server implementation SHOULD attempt to prevent system 1159 disruption due to incremental processing of the YANG Patch edit list. 1160 It may be possible to construct an attack on such a RESTCONF server, 1161 which relies on the edit processing order mandated by YANG Patch. A 1162 server SHOULD apply only the fully validated configuration to the 1163 underlying system. For example, an edit list which deleted an 1164 interface and then recreated it could cause system disruption if the 1165 edit list was incrementally applied. 1167 A RESTCONF server implementation SHOULD attempt to prevent system 1168 disruption due to excessive resource consumption required to fulfill 1169 YANG Patch edit requests. It may be possible to construct an attack 1170 on such a RESTCONF server, which attempts to consume all available 1171 memory or other resource types. 1173 6. Normative References 1175 [I-D.ietf-netconf-restconf] 1176 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1177 Protocol", draft-ietf-netconf-restconf-18 (work in 1178 progress), October 2016. 1180 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1181 Requirement Levels", BCP 14, RFC 2119, March 1997. 1183 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1184 DOI 10.17487/RFC3688, January 2004, 1185 . 1187 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1188 RFC 5789, March 2010. 1190 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1191 Network Configuration Protocol (NETCONF)", RFC 6020, 1192 October 2010. 1194 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1195 and A. Bierman, Ed., "Network Configuration Protocol 1196 (NETCONF)", RFC 6241, June 2011. 1198 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1199 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1200 2014, . 1202 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1203 Protocol (HTTP/1.1): Message Syntax and Routing", 1204 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1205 . 1207 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1208 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1210 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1211 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1212 . 1214 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1215 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1216 . 1218 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1219 RFC 7952, DOI 10.17487/RFC7952, August 2016, 1220 . 1222 [W3C.REC-xml-20081126] 1223 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 1224 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 1225 Edition)", World Wide Web Consortium Recommendation REC- 1226 xml-20081126, November 2008, 1227 . 1229 Appendix A. Acknowledgements 1231 The authors would like to thank the following people for their 1232 contributions to this document: Rex Fernando. 1234 Contributions to this material by Andy Bierman are based upon work 1235 supported by the The Space & Terrestrial Communications Directorate 1236 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 1237 and conclusions or recommendations expressed in this material are 1238 those of the author(s) and do not necessarily reflect the views of 1239 The Space & Terrestrial Communications Directorate (S&TCD). 1241 Appendix B. Change Log 1243 -- RFC Ed.: remove this section before publication. 1245 The YANG Patch issue tracker can be found here: https://github.com/ 1246 netconf-wg/yang-patch/issues 1248 B.1. v12 to v13 1250 o clarifications based on IESG reviews 1252 B.2. v11 to v12 1254 o clarify target resource must exist 1256 o fix errors in some examples 1258 o change application/yang-patch-xml to application/yang-patch+xml 1260 o clarified some section titles 1261 o clarified error responses for multiple edit instances 1263 o made patch-id field mandatory 1265 o referenced NETCONF operation attribute 1267 B.3. v10 to v11 1269 o change application/yang-patch to application/yang-patch-xml 1271 o change server to RESTCONF server and remove NETCONF server term 1273 o change client to RESTCONF client and remove NETCONF client term 1275 o clarified that YANG 1.0 content can be used in a YANG Patch 1276 implementation 1278 o clarified more terminology 1280 o fixed missing keys in edit examples 1282 o added insert list example 1284 B.4. v09 to v10 1286 o change yang-patch+xml to yang-patch 1288 o clarify application/yang-patch+json media type 1290 o add edit datastore example 1292 o change data-resource-offset typedef so it is consistent for XML 1293 and JSON 1295 B.5. v08 to v09 1297 o change RFC 7158 reference to RFC 7159 reference 1299 o change RFC 2616 reference to RFC 7230 reference 1301 o remove unused HTTP terms 1303 o remove import-by-revision of ietf-restconf; not needed 1305 o change application/yang.patch media type to application/yang-patch 1307 o remove application/yang.patch-status media type; use application/ 1308 yang-data instead 1310 B.6. v07 to v08 1312 o clarified target datastore and target data node terms 1314 o clarified that target leaf can be single forward slash '/' 1316 o added Successful edit response handling section 1318 o clarified that YANG Patch draft is for RESTCONF protocol only but 1319 may be defined for other protocols outside this document 1321 o clarified that YANG Patch draft is for configuration datastores 1322 only but may be defined for other datastore types outside this 1323 document 1325 o fixed typos 1327 B.7. v06 to v07 1329 o converted YANG module to YANG 1.1 1331 o changed anyxml value to anydata value 1333 o updated import revision date for ietf-restconf 1335 o updated revision date for ietf-yang-patch because import-by- 1336 revision date needed to be changed 1338 B.8. v05 to v06 1340 o changed errors example so a full request and error response is 1341 shown in XML format 1343 o fixed error-path to match instance-identifier encoding for both 1344 XML and JSON 1346 o added references for YANG to JSON and YANG Metadata drafts 1348 o clarified that YANG JSON drafts are used for encoding, not plain 1349 JSON 1351 B.9. v04 to v05 1353 o updated reference to RESTCONF 1355 B.10. v03 to v04 1357 o removed NETCONF specific text 1359 o changed data-resource-offset typedef from a relative URI to an 1360 XPath absolute path expression 1362 o clarified insert operation 1364 o removed requirement that edits MUST be applied in ascending order 1366 o change SHOULD keep datastore unchanged on error to MUST (this is 1367 required by HTTP PATCH) 1369 o removed length restriction on 'comment' leaf 1371 o updated YANG tree for example-jukebox library 1373 B.11. v02 to v03 1375 o added usage of restconf-media-type extension to map the yang-patch 1376 and yang-patch-status groupings to media types 1378 o added yang-patch RESTCONF capability URI 1380 o Added sub-section for terms used from RESTCONF 1382 o filled in security considerations section 1384 B.12. v01 to v02 1386 o Reversed order of change log 1388 o Clarified anyxml structure of "value" parameter within a YANG 1389 patch request (github issue #1) 1391 o Updated RESTCONF reference 1393 o Added note to open issues section to check github instead 1395 B.13. v00 to v01 1397 o Added text requiring support for Accept-Patch header field, and 1398 removed 'Identification of YANG Patch capabilities' open issue. 1400 o Removed 'location' leaf from yang-patch-status grouping 1401 o Removed open issue 'Protocol independence' because the location 1402 leaf was removed. 1404 o Removed open issue 'RESTCONF coupling' because there is no concern 1405 about a normative reference to RESTCONF. There may need to be a 1406 YANG 1.1 mechanism to allow protocol template usage (instead of 1407 grouping wrapper). 1409 o Removed open issue 'Is the delete operation needed'. It was 1410 decided that both delete and remove should remain as operations 1411 and clients can choose which one to use. This is not an 1412 implementation burden on the server. 1414 o Removed open issue 'global-errors needed'. It was decided that 1415 they are needed as defined because the global is needed and 1416 the special key value for edit=global error only allows for 1 1417 global error. 1419 o Removed open issue 'Is location leaf needed'. It was decided that 1420 it is not needed so this leaf has been removed. 1422 o Removed open issue 'Bulk editing support in yang-patch-status'. 1423 The 'location' leaf has been removed so this issue is no longer 1424 applicable. 1426 o Removed open issue 'Edit list mechanism'. Added text to the 1427 'edit' list description-stmt about how the individual edits must 1428 be processed. There is no concern about duplicate edits which 1429 cause intermediate results to be altered by subsequent edits in 1430 the same edit list. 1432 B.14. bierman:yang-patch-00 to ietf:yang-patch-00 1434 o Created open issues section 1436 Appendix C. Open Issues 1438 -- RFC Ed.: remove this section before publication. 1440 Refer to the github issue tracker for any open issues: 1442 https://github.com/netconf-wg/yang-patch/issues 1444 Appendix D. Example YANG Module 1446 The example YANG module used in this document represents a simple 1447 media jukebox interface. The "example-jukebox" YANG module is 1448 defined in [I-D.ietf-netconf-restconf]. 1450 YANG tree diagram for "example-jukebox" Module: 1452 +--rw jukebox! 1453 +--rw library 1454 | +--rw artist* [name] 1455 | | +--rw name string 1456 | | +--rw album* [name] 1457 | | +--rw name string 1458 | | +--rw genre? identityref 1459 | | +--rw year? uint16 1460 | | +--rw admin 1461 | | | +--rw label? string 1462 | | | +--rw catalogue-number? string 1463 | | +--rw song* [name] 1464 | | +--rw name string 1465 | | +--rw location string 1466 | | +--rw format? string 1467 | | +--rw length? uint32 1468 | +--ro artist-count? uint32 1469 | +--ro album-count? uint32 1470 | +--ro song-count? uint32 1471 +--rw playlist* [name] 1472 | +--rw name string 1473 | +--rw description? string 1474 | +--rw song* [index] 1475 | +--rw index uint32 1476 | +--rw id leafref 1477 +--rw player 1478 +--rw gap? decimal64 1480 rpcs: 1482 +---x play 1483 +--ro input 1484 +--ro playlist string 1485 +--ro song-number uint32 1487 D.1. YANG Patch Examples 1489 This section includes RESTCONF examples. Most examples are shown in 1490 JSON encoding [RFC7159], and some are shown in XML encoding 1491 [W3C.REC-xml-20081126]. 1493 D.1.1. Add Resources: Error 1495 The following example shows several songs being added to an existing 1496 album. Each edit contains one song. The first song already exists, 1497 so an error will be reported for that edit. The rest of the edits 1498 were not attempted, since the first edit failed. The XML encoding is 1499 used in this example. 1501 Request from the RESTCONF client: 1503 PATCH /restconf/data/example-jukebox:jukebox/\ 1504 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1505 Host: example.com 1506 Accept: application/yang-data+xml 1507 Content-Type: application/yang-patch+xml 1509 1510 add-songs-patch 1511 1512 edit1 1513 create 1514 /song=Bridge%20Burning 1515 1516 1517 Bridge Burning 1518 /media/bridge_burning.mp3 1519 MP3 1520 288 1521 1522 1523 1524 1525 edit2 1526 create 1527 /song=Rope 1528 1529 1530 Rope 1531 /media/rope.mp3 1532 MP3 1533 259 1534 1535 1536 1537 1538 edit3 1539 create 1540 /song=Dear%20Rosemary 1541 1542 1543 Dear Rosemary 1544 /media/dear_rosemary.mp3 1545 MP3 1546 269 1547 1548 1549 1550 1552 XML Response from the RESTCONF server: 1554 HTTP/1.1 409 Conflict 1555 Date: Mon, 23 Apr 2012 13:01:20 GMT 1556 Server: example-server 1557 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1558 Content-Type: application/yang-data+xml 1560 1562 add-songs-patch 1563 1564 1565 edit1 1566 1567 1568 application 1569 data-exists 1570 1572 /jb:jukebox/jb:library 1573 /jb:artist[jb:name='Foo Fighters'] 1574 /jb:album[jb:name='Wasting Light'] 1575 /jb:song[jb:name='Burning Light'] 1576 1577 1578 Data already exists, cannot be created 1579 1580 1581 1582 1583 1584 1586 JSON Response from the RESTCONF server: 1588 The following response is shown in JSON format to highlight the 1589 difference in the "error-path" object encoding. For JSON, the 1590 instance-identifier encoding in the "JSON Encoding of YANG Data" 1591 draft is used. 1593 HTTP/1.1 409 Conflict 1594 Date: Mon, 23 Apr 2012 13:01:20 GMT 1595 Server: example-server 1596 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1597 Content-Type: application/yang-data+json 1599 { 1600 "ietf-yang-patch:yang-patch-status" : { 1601 "patch-id" : "add-songs-patch", 1602 "edit-status" : { 1603 "edit" : [ 1604 { 1605 "edit-id" : "edit1", 1606 "errors" : { 1607 "error" : [ 1608 { 1609 "error-type": "application", 1610 "error-tag": "data-exists", 1611 "error-path": "/example-jukebox:jukebox/library\ 1612 /artist[name='Foo Fighters']\ 1613 /album[name='Wasting Light']\ 1614 /song[name='Burning Light']", 1615 "error-message": 1616 "Data already exists, cannot be created" 1617 } 1618 ] 1619 } 1620 } 1621 ] 1622 } 1623 } 1624 } 1626 D.1.2. Add Resources: Success 1628 The following example shows several songs being added to an existing 1629 album. 1631 o Each of 2 edits contains one song. 1633 o Both edits succeed and new sub-resources are created 1635 Request from the RESTCONF client: 1637 PATCH /restconf/data/example-jukebox:jukebox/\ 1638 library/artist=Foo%20Fighters/album=Wasting%20Light \ 1639 HTTP/1.1 1640 Host: example.com 1641 Accept: application/yang-data+json 1642 Content-Type: application/yang-patch+json 1644 { 1645 "ietf-yang-patch:yang-patch" : { 1646 "patch-id" : "add-songs-patch-2", 1647 "edit" : [ 1648 { 1649 "edit-id" : "edit1", 1650 "operation" : "create", 1651 "target" : "/song=Rope", 1652 "value" : { 1653 "song" : [ 1654 { 1655 "name" : "Rope", 1656 "location" : "/media/rope.mp3", 1657 "format" : "MP3", 1658 "length" : 259 1659 } 1660 ] 1661 } 1662 }, 1663 { 1664 "edit-id" : "edit2", 1665 "operation" : "create", 1666 "target" : "/song=Dear%20Rosemary", 1667 "value" : { 1668 "song" : [ 1669 { 1670 "name" : "Dear Rosemary", 1671 "location" : "/media/dear_rosemary.mp3", 1672 "format" : "MP3", 1673 "length" : 269 1674 } 1675 ] 1676 } 1677 } 1678 ] 1679 } 1680 } 1682 Response from the RESTCONF server: 1684 HTTP/1.1 200 OK 1685 Date: Mon, 23 Apr 2012 13:01:20 GMT 1686 Server: example-server 1687 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1688 Content-Type: application/yang-data+json 1690 { 1691 "ietf-yang-patch:yang-patch-status" : { 1692 "patch-id" : "add-songs-patch-2", 1693 "ok" : [null] 1694 } 1695 } 1697 D.1.3. Insert list entry example 1699 The following example shows a song being inserted within an existing 1700 playlist. Song "6" in playlist "Foo-One" is being inserted after 1701 song "5" in the playlist. The operation succeeds, so a non-error 1702 reply example can be shown. 1704 Request from the RESTCONF client: 1706 PATCH /restconf/data/example-jukebox:jukebox/\ 1707 playlist=Foo-One HTTP/1.1 1708 Host: example.com 1709 Accept: application/yang-data+json 1710 Content-Type: application/yang-patch+json 1712 { 1713 "ietf-yang-patch:yang-patch" : { 1714 "patch-id" : "move-song-patch", 1715 "comment" : "Insert song 6 after song 5", 1716 "edit" : [ 1717 { 1718 "edit-id" : "edit1", 1719 "operation" : "insert", 1720 "target" : "/song=6", 1721 "point" : "/song=5", 1722 "where" : "after", 1723 "value" : { 1724 "example-jukebox:song" : [ 1725 { 1726 "name" : "Dear Prudence", 1727 "location" : "/media/dear_prudence.mp3", 1728 "format" : "MP3", 1729 "length" : 236 1730 } 1731 ] 1732 } 1733 } 1734 ] 1735 } 1736 } 1738 Response from the RESTCONF server: 1740 HTTP/1.1 200 OK 1741 Date: Mon, 23 Apr 2012 13:01:20 GMT 1742 Server: example-server 1743 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1744 Content-Type: application/yang-data+json 1746 { 1747 "ietf-yang-patch:yang-patch-status" : { 1748 "patch-id" : "move-song-patch", 1749 "ok" : [null] 1750 } 1751 } 1753 D.1.4. Move list entry example 1755 The following example shows a song being moved within an existing 1756 playlist. Song "1" in playlist "Foo-One" is being moved after song 1757 "3" in the playlist. Note that no "value" parameter is needed for a 1758 "move" operation. The operation succeeds, so a non-error reply 1759 example can be shown. 1761 Request from the RESTCONF client: 1763 PATCH /restconf/data/example-jukebox:jukebox/\ 1764 playlist=Foo-One HTTP/1.1 1765 Host: example.com 1766 Accept: application/yang-data+json 1767 Content-Type: application/yang-patch+json 1769 { 1770 "ietf-yang-patch:yang-patch" : { 1771 "patch-id" : "move-song-patch", 1772 "comment" : "Move song 1 after song 3", 1773 "edit" : [ 1774 { 1775 "edit-id" : "edit1", 1776 "operation" : "move", 1777 "target" : "/song=1", 1778 "point" : "/song=3", 1779 "where" : "after" 1780 } 1781 ] 1782 } 1783 } 1785 Response from the RESTCONF server: 1787 HTTP/1.1 200 OK 1788 Date: Mon, 23 Apr 2012 13:01:20 GMT 1789 Server: example-server 1790 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1791 Content-Type: application/yang-data+json 1793 { 1794 "ietf-restconf:yang-patch-status" : { 1795 "patch-id" : "move-song-patch", 1796 "ok" : [null] 1797 } 1798 } 1800 D.1.5. Edit datastore resource example 1802 The following example shows how 3 top-level data nodes from different 1803 modules can be edited at the same time. 1805 Example module "foo" defines leaf X. Example module "bar" defines 1806 container Y, with child leafs A and B. Example module "baz" defines 1807 list Z, with key C and child leafs D and E. 1809 Request from the RESTCONF client: 1811 PATCH /restconf/data HTTP/1.1 1812 Host: example.com 1813 Accept: application/yang-data+json 1814 Content-Type: application/yang-patch+json 1816 { 1817 "ietf-yang-patch:yang-patch" : { 1818 "patch-id" : "datastore-patch-1", 1819 "comment" : "Edit 3 top-level data nodes at once", 1820 "edit" : [ 1821 { 1822 "edit-id" : "edit1", 1823 "operation" : "create", 1824 "target" : "/foo:X", 1825 "value" : { 1826 "foo:X" : 42 1827 } 1828 }, 1829 { 1830 "edit-id" : "edit2", 1831 "operation" : "merge", 1832 "target" : "/bar:Y", 1833 "value" : { 1834 "bar:Y" : { 1835 "A" : "test1", 1836 "B" : 99 1837 } 1838 } 1839 }, 1840 { 1841 "edit-id" : "edit3", 1842 "operation" : "replace", 1843 "target" : "/baz:Z=2", 1844 "value" : { 1845 "baz:Z" : [ 1846 { 1847 "C" : 2, 1848 "D" : 100, 1849 "E" : false 1850 } 1851 ] 1852 } 1853 } 1854 ] 1855 } 1856 } 1858 Response from the RESTCONF server: 1860 HTTP/1.1 200 OK 1861 Date: Mon, 23 Apr 2012 13:02:20 GMT 1862 Server: example-server 1863 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1864 Content-Type: application/yang-data+json 1866 { 1867 "ietf-yang-patch:yang-patch-status" : { 1868 "patch-id" : "datastore-patch-1", 1869 "ok" : [null] 1870 } 1871 } 1873 Authors' Addresses 1875 Andy Bierman 1876 YumaWorks 1878 Email: andy@yumaworks.com 1880 Martin Bjorklund 1881 Tail-f Systems 1883 Email: mbj@tail-f.com 1885 Kent Watsen 1886 Juniper Networks 1888 Email: kwatsen@juniper.net