YANG Patch Media Type
Extracted elements (26)
Edits within a YANG Patch are conceptually applied in sequence to a copy of the target datastore, validated after all edits succeed, and only then committed. This all-or-nothing transactional model avoids partial state corruption and enables precise error reporting per edit.
Target data node resolution uses absolute path expressions when the request URI identifies a datastore resource, and relative path expressions when it identifies a configuration data resource. This allows YANG Patch to operate at both the datastore level and within sub-trees.
The 'patch-id' field is included to support debugging and audit logging. Clients SHOULD generate unique patch-id values to distinguish transactions from multiple clients in server audit logs.
YANG Patch was created because the 'plain patch' mechanism in RESTCONF (RFC 8040) does not provide sufficient client control: it cannot edit multiple sub-resources in one request, lacks precise per-operation semantics, and does not guarantee processing order or per-edit error reporting.
Although the 'ietf-yang-patch' YANG module is written in YANG version 1.1 (RFC 7950), an implementation of YANG Patch can be used with content defined in YANG version 1 (RFC 6020) as well.
YANG Patch can only edit data resources; the PATCH method cannot replace the datastore resource. A complete datastore cannot be replaced in the same manner as the NETCONF <copy-config> operation.
Each edit within a YANG Patch MUST identify exactly one data resource instance. If an edit represents more than one resource instance or does not identify any existing instance (and the operation is not 'create'), the request MUST NOT be processed; a 'yang-patch-status' response MUST be sent identifying the invalid edits.
If a YANG Patch is completed without errors, the RESTCONF server MUST return a 'yang-patch-status' message with a 'global-status' choice set to 'ok'.
If the entire patch document cannot be successfully applied, the server MUST NOT apply any of the changes. A PATCH request MUST be applied atomically.
If the RESTCONF server supports the YANG Patch media type, the ':yang-patch' RESTCONF capability MUST be present in the 'capability' leaf-list in the 'ietf-restconf-monitoring' module.
The RESTCONF server MUST return the 'Accept-Patch' header field in an OPTIONS response as specified in RFC 5789, including the YANG Patch media types, so clients can determine supported encoding formats.
The 'target' leaf MUST NOT contain a single forward slash ('/') when the request URI identifies a datastore resource, since that would identify the datastore itself rather than a data resource.
The target resource MUST identify exactly one resource instance. If more than one instance is identified, the request MUST NOT be processed and a '400 Bad Request' MUST be sent. If no existing instance is identified, the request MUST NOT be processed and a '404 Not Found' MUST be sent.
Seven edit operations are defined: 'create' (create if not exists, error if exists), 'delete' (delete if exists, error if not), 'insert' (insert new user-ordered entry), 'merge' (merge with target, create if not exists), 'move' (reorder user-ordered entry), 'replace' (replace target), and 'remove' (delete if exists, no error if not).
The 'point' and 'where' leaves apply only to 'insert' and 'move' operations. 'where' is an enumeration of 'before', 'after', 'first', or 'last' with a default of 'last'. 'point' provides the target-resource-offset for 'before' and 'after' cases.
The 'target-resource-offset' typedef is a string type encoding a sub-resource path within the target resource, using the same encoding rules as a data resource identifier in a RESTCONF request URI (per RFC 8040 Section 3.5.3).
The 'yang-patch' container defines an ordered patch request with fields: mandatory 'patch-id' (string), optional 'comment' (string), and user-ordered 'edit' list keyed by 'edit-id'. Each edit contains 'edit-id', mandatory 'operation' (enumeration), mandatory 'target', optional 'point', optional 'where', and optional 'value'.
The 'yang-patch-status' container is the server response and contains 'patch-id', a 'global-status' choice (either 'global-errors' using the rc:errors grouping or 'ok' empty leaf), and an 'edit-status' container with per-edit status (either 'ok' or 'errors').
This document registers one RESTCONF capability identifier ':yang-patch' with identifier 'urn:ietf:params:restconf:capability:yang-patch:1.0' in the 'RESTCONF Capability URNs' registry (RFC 8040), under IETF Review policy.
This document registers the YANG module 'ietf-yang-patch' in the 'YANG Module Names' registry (RFC 6020) with namespace 'urn:ietf:params:xml:ns:yang:ietf-yang-patch' and prefix 'ypatch'.
This document registers two media types: 'application/yang-patch+xml' and 'application/yang-patch+json', both with UTF-8 encoding and no required parameters, for use with YANG Patch request messages.
A RESTCONF server implementation SHOULD attempt to prevent system disruption due to excessive resource consumption required to fulfill YANG Patch edit requests, as an attacker may construct a patch designed to exhaust available memory or other resources.
A RESTCONF server SHOULD apply only the fully validated configuration to the underlying system to prevent disruption from incremental edit processing. For example, an edit list that deletes and recreates an interface could cause disruption if applied incrementally.
For RESTCONF, both the client and server MUST be authenticated according to Section 2 of RFC 8040. If the entire YANG Patch request cannot be completed, no configuration changes are made. Message integrity is provided by the RESTCONF protocol.
YANG Patch requests use media type 'application/yang-patch+xml' or 'application/yang-patch+json' with UTF-8 charset. The 'value' anydata node is only present for 'create', 'merge', 'replace', and 'insert' operations and contains the target resource encoded per RFC 7950 (XML) or RFC 7951 (JSON).
YANG Patch Status responses use media type 'application/yang-data+xml' or 'application/yang-data+json'. The 'error-path' field uses instance-identifier encoding per XML namespace rules for XML and per RFC 7951 for JSON, which differ in syntax.