YANG Patch [RFC8072] is an "ordered 'edit' list" approach that provides RESTCONF client developers with more precise RESTCONF client control of the edit procedure than the "plain patch" or plain POST methods.

YANG Patch operation is invoked by the RESTCONF client by sending a PATCH method request with a representation using either the media type "application/yang-patch+xml" or "application/yang-patch+json".  This message-body representing the YANG Patch input parameters MUST be present.


YANG Patch has some features that are not possible with the "plain-patch" mechanism defined in RESTCONF [RFC8040]:

  1. YANG Patch allows multiple sub-resources to be edited within the same PATCH method.
  2. YANG Patch allows a more precise edit operation than the "plain patch" mechanism. There are seven operations supported ("create", "delete", "insert", "merge", "move", "replace", and "remove").
  3. YANG Patch uses an "edit" list with an explicit processing order. The edits are processed in client-specified order, and error processing can be precise even when multiple errors occur in the same YANG Patch request.


The YANG Patch "patch-id" may be useful for debugging and present in any audit logging records generated by the RESTCONF server for a patch.
The RESTCONF server returns the "Accept-Patch" header field in an OPTIONS response which includes the media type for YANG Patch.  This is needed by a client to determine the message-encoding formats supported by the server (e.g., XML, JSON, or both).  The following is an example of an "Accept-Patch" header:

    Accept-Patch: application/yang-patch+xml,application/yang-patch+json

Note that YANG Patch can only edit data resources. The PATCH method cannot be used to replace the datastore resource. Although the "ietf-yang-patch" YANG module is written using YANG version 1.1, an implementation of YANG Patch can be used with content defined in YANG version 1 as well.
A YANG Patch can be encoded in XML format as well as in JSON format.


Each YANG Patch edit specifies one edit operation on the target data node. The set of operations is aligned with the NETCONF edit operations but also includes some new operations.


YANG Patch Edit Operations

Operation
Description
create
create a new data resource if it does not already exist; if it already exists, return an error
delete
delete a data resource if it already exists; if it does not exist, return an error
insert
insert a new user-ordered data resource
merge
merge the edit value with the target data resource; create if it does not already exist
move
reorder the target data resource
replace
replace the target data resource with the edit value
remove
remove a data resource if it already exists


 

YANG Patch Examples

Add Resources: Success


The following example shows several songs being added to an existing album.

    - Each of two edits contains one song.
    - Both edits succeed, and new sub-resources are created.

Request from the RESTCONF client:


PATCH /restconf/data/example-jukebox:jukebox/\
  library/artist=Foo%20Fighters/album=Wasting%20Light 
  Host: example.com
  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=Rope",
              "value" : {
                "song" : [
                  {
                    "name" : "Rope",
                    "location" : "/media/rope.mp3",
                    "format" : "MP3",
                    "length" : 259
                  }
                ]
              }
            },
            {
              "edit-id" : "edit2",
              "operation" : "create",
              "target" : "/song=Dear%20Rosemary",
              "value" : {
                "song" : [
                  {
                    "name" : "Dear Rosemary",
                    "location" : "/media/dear_rosemary.mp3",
                    "format" : "MP3",
                    "length" : 269
                  }
                ]
              }
            }
          ]
        }
      }


   Response from the RESTCONF server:


      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
      Content-Type: application/yang-data+json

      {
        "ietf-yang-patch:yang-patch-status" : {
          "patch-id" : "add-songs-patch-2",
          "ok" : [null]
        }
      }


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. XML encoding is used in this example.
Request from the RESTCONF client:


      PATCH /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml
      Content-Type: application/yang-patch+xml

      <yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
        <patch-id>add-songs-patch</patch-id>
        <edit>
          <edit-id>edit1</edit-id>
          <operation>create</operation>
          <target>/song=Bridge%20Burning</target>
          <value>
            <song xmlns="http://example.com/ns/example-jukebox">
              <name>Bridge Burning</name>
              <location>/media/bridge_burning.mp3</location>
              <format>MP3</format>
              <length>288</length>
            </song>
          </value>
        </edit>
        <edit>
          <edit-id>edit2</edit-id>
          <operation>create</operation>
          <target>/song=Rope</target>
          <value>
            <song xmlns="http://example.com/ns/example-jukebox">
              <name>Rope</name>
              <location>/media/rope.mp3</location>
              <format>MP3</format>
              <length>259</length>
            </song>
          </value>
        </edit>
        <edit>
          <edit-id>edit3</edit-id>
          <operation>create</operation>
          <target>/song=Dear%20Rosemary</target>
          <value>
            <song xmlns="http://example.com/ns/example-jukebox">
              <name>Dear Rosemary</name>
              <location>/media/dear_rosemary.mp3</location>
              <format>MP3</format>
              <length>269</length>
            </song>
          </value>
        </edit>
      </yang-patch>


XML response from the RESTCONF server:


      HTTP/1.1 409 Conflict
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
      Content-Type: application/yang-data+xml

      <yang-patch-status
         xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
        <patch-id>add-songs-patch</patch-id>
        <edit-status>
          <edit>
             <edit-id>edit1</edit-id>
             <errors>
                <error>
                   <error-type>application</error-type>
                   <error-tag>data-exists</error-tag>
                   <error-path
                     xmlns:jb="http://example.com/ns/example-jukebox">
                     /jb:jukebox/jb:library
                     /jb:artist[jb:name='Foo Fighters']
                     /jb:album[jb:name='Wasting Light']
                     /jb:song[jb:name='Bridge Burning']
                   </error-path>
                   <error-message>
                     Data already exists; cannot be created
                   </error-message>
                </error>
             </errors>
          </edit>
       </edit-status>
     </yang-patch-status>


For more YANG Patch examples and details refer to YANG Patch Examples.