skip to content

When does a RESTCONF client need a YANG Patch (RFC 8072) instead of a plain PATCH, and what does it guarantee about edit order and atomicity?

level: seniorimportance: nice to knowfreq 6%

answer

  1. merge is the only plain verb
  2. seven edit operations
  3. an ordered list of edits
  4. validate after the last edit
  5. per-edit status in the reply

basics

~20 s

When one request must mix operations — create, delete, insert, merge, move, replace or remove — across several nodes. YANG Patch applies its edits in list order to a copy, validates the result once, and changes nothing if any edit fails.

solid answer

~50 s

A plain `PATCH` in RESTCONF can only *merge*: it creates or updates children of one target but cannot delete, replace, reorder or guard a create. **YANG Patch** (RFC 8072) is a second PATCH media type, `application/yang-patch+json` or `+xml`, whose body is an ordered `edit` list. Each edit has an `edit-id`, one of seven operations, a `target` path and, where needed, a `value`. The server applies the edits in ascending order to a conceptual copy of the datastore, validates the result against the YANG constraints only after the last edit, and applies it only if everything succeeded; any error leaves the datastore unchanged. The reply is a `yang-patch-status` naming the edit that failed. Use it for ordered multi-step changes — delete one entry and create its replacement, insert into a user-ordered list — that must land together.

code

json · 13 lines
json
{
  "ietf-yang-patch:yang-patch": {
    "patch-id": "relabel-uplinks",
    "edit": [
      {"edit-id": "e1", "operation": "remove",
       "target": "/interface=uplink-1/description"},
      {"edit-id": "e2", "operation": "merge",
       "target": "/interface=uplink-2",
       "value": {"ietf-interfaces:interface": [
         {"name": "uplink-2", "description": "to core-2"}]}}
    ]
  }
}

go deeper

for a junior

Recall that RESTCONF has a second patch format, YANG Patch, for changes that plain PATCH's merge cannot express, such as deletes.

for a middle

Explain the request shape — patch-id, an ordered edit list, the seven operations — and how a client checks that the server supports it.

for a senior

Show how ordered, validate-at-the-end, all-or-nothing processing lets one request delete, create and reorder safely, and how to read a per-edit failure.

for a principal

Decide when a change pipeline should batch edits into one YANG Patch versus separate requests, weighing atomicity against blast radius and debuggability.

## What plain PATCH cannot express RFC 8040 gives RESTCONF one built-in patch format, **plain patch**: a body in `application/yang-data+json` or `+xml` that is **merged** into the target. That covers "set these leaves" well and nothing else: - it **cannot delete** a child — RFC 8040 §4.6.1 says so outright; - it cannot say **"create, and fail if it already exists"**, or **"replace this subtree but not its neighbours"**; - it cannot **reorder** an `ordered-by user` list; - it is one merge, so a change that also needs a delete or a reorder takes several requests — and a failure halfway leaves the device between states. RFC 8040 anticipated this: PATCH is extensible by media type, and the server lists the types it accepts in `Accept-Patch`. **YANG Patch** (RFC 8072, Standards Track, February 2017) is the one the IETF defined. ## The request The client sends `PATCH` to a target URI — the datastore `{+restconf}/data` or one configuration data resource — with `Content-Type: application/yang-patch+json` (or `+xml`). The body is a `yang-patch` container: - **`patch-id`** — a client-chosen name for the whole patch, which servers SHOULD put in audit logs; - **`comment`** — optional free text, also for the audit trail; - **`edit`** — a list, keyed by **`edit-id`** and `ordered-by user`, each entry holding: - **`operation`** — one of the seven below; - **`target`** — a path to the node the edit touches, absolute when the request targets the datastore, relative to the target resource otherwise; - **`point`** and **`where`** — for `insert` and `move`: `before`, `after`, `first` or `last`; - **`value`** — the content, used only by `create`, `merge`, `replace` and `insert`. ## The seven operations | Operation | Effect | |---|---| | `create` | create the node; error if it already exists | | `delete` | delete the node; error if it does not exist | | `insert` | insert a new entry into a user-ordered list or leaf-list | | `merge` | merge the value; create the node if absent | | `move` | reorder an existing entry in a user-ordered list | | `replace` | replace the node with the value | | `remove` | delete the node if present; no error if absent | `create`, `delete`, `merge`, `replace` and `remove` mean exactly what the NETCONF `operation` attribute means (RFC 6241 §7.2); `insert` and `move` are new. ## Order and atomicity RFC 8072's module spells out the processing: 1. The first edit is applied to a **conceptual copy** of the target datastore. 2. Each later edit is applied to the result of the edits before it, in ascending order. 3. Only after **all** edits succeed is the result **validated against the YANG constraints**. 4. If that succeeds, the server applies the result to the datastore. If any error occurs, the datastore **must not be changed**. Two consequences follow. Intermediate states may break constraints — a `delete` that briefly leaves a `leafref` dangling until a later `create` repairs it is fine, because nothing is checked until the end. And there is no partial success: `edit3` failing undoes `edit1` and `edit2`. The security section adds that a server SHOULD push only the fully validated configuration to the running system, not each edit as it is processed. Atomicity alone is not what sets YANG Patch apart: RFC 8072 notes that any PATCH request must be applied atomically. Its additions are the **mixed operations**, the **explicit order** and **per-edit error reporting**. ## The reply - Success: `200 OK` with a `yang-patch-status` whose `global-status` is `ok`. - Failure: an error status — RFC 8072's example answers a duplicate `create` with `409 Conflict` — and a `yang-patch-status` whose `edit-status` names the failing `edit-id` with its `error-tag` and `error-path`. In RFC 8072's example, the edits after the failing one are not attempted. A request rejected before any edit is processed gets a plain HTTP error instead. ## Limits and discovery - The target URI must identify exactly one existing instance (`400` if it names several, `404` if none), and each edit must identify exactly one node instance. - YANG Patch edits data resources; it cannot replace the whole datastore the way `<copy-config>` or a `PUT` on `{+restconf}/data` does, and it offers no way to choose a datastore. - Support is optional. A client checks `Accept-Patch` in an `OPTIONS` response, or the `:yang-patch` capability (`urn:ietf:params:restconf:capability:yang-patch:1.0`) in the server's monitoring data, before relying on it.

  • In a YANG Patch, what is the practical difference between the delete and remove operations?
    Both take the target node out of the configuration. `delete` fails if the node does not exist, and because the patch is all-or-nothing, that failure aborts every other edit. `remove` silently succeeds when the node is already absent. Use `delete` when absence would mean the device is not in the state you planned for, and `remove` for idempotent clean-up.
  • Why can a YANG Patch delete a node that another node's leafref points at, then fix the reference later in the same patch?
    RFC 8072 applies the edits in order to a conceptual copy of the datastore and validates against YANG constraints only once, after the last edit. A dangling reference in the middle is never checked; only the final result must be valid. Split the same change into two separate requests and the first would normally be refused.

saying these in an interview costs you the question

  • YANG Patch is the only RESTCONF PATCH that is applied atomically.
  • Each YANG Patch edit is validated and committed as soon as it is processed.
  • If edit three fails, edits one and two stay applied.
  • A YANG Patch can replace the entire datastore in one request.
  • Every RESTCONF server must accept application/yang-patch+json.