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]:
- YANG Patch allows multiple sub-resources to be edited within the same PATCH method.
- 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").
- 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.