One document matched: draft-ietf-netconf-yang-patch-05.xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
<?rfc toc="yes"?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no"?>
<?rfc strict="yes"?>
<rfc ipr="trust200902" category="std"
docName="draft-ietf-netconf-yang-patch-05" >
<front>
<title abbrev="YANG Patch">YANG Patch Media Type</title>
<author initials="A" surname="Bierman" fullname='Andy Bierman' >
<organization>YumaWorks</organization>
<address>
<email>andy@yumaworks.com</email>
</address>
</author>
<author initials="M" surname="Bjorklund" fullname='Martin Bjorklund' >
<organization>Tail-f Systems</organization>
<address>
<email>mbj@tail-f.com</email>
</address>
</author>
<author initials="K" surname="Watsen" fullname='Kent Watsen' >
<organization>Juniper Networks</organization>
<address>
<email>kwatsen@juniper.net</email>
</address>
</author>
<date/>
<abstract>
<t>
This document describes a method for applying patches
to NETCONF datastores using data defined with the YANG
data modeling language.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
There is a need for standard mechanisms to patch NETCONF <xref target="RFC6241"/>
datastores which contain conceptual data that conforms to
schema specified with YANG <xref target="RFC6020"/>. An "ordered edit list"
approach is needed to provide client developers with a simpler
edit request format that can be more efficient and also allow
more precise client control of the transaction procedure than
existing mechanisms.
</t>
<t>
This document defines a media type for a YANG-based editing
mechanism that can be used with the HTTP PATCH method <xref target="RFC5789"/>.
YANG Patch is designed to support the RESTCONF protocol,
defined in <xref target="I-D.ietf-netconf-restconf"/>.
</t>
<section title="Terminology">
<t>
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14, <xref target="RFC2119"/>.
</t>
<section title="NETCONF">
<t>
The following terms are defined in <xref target="RFC6241"/>:
</t>
<t>
<list style="symbols">
<t>
client
</t>
<t>
configuration data
</t>
<t>
datastore
</t>
<t>
configuration datastore
</t>
<t>
protocol operation
</t>
<t>
running configuration datastore
</t>
<t>
server
</t>
<t>
state data
</t>
<t>
user
</t>
</list>
</t>
</section>
<section title="HTTP">
<t>
The following terms are defined in <xref target="RFC2616"/>:
</t>
<t>
<list style="symbols">
<t>
entity tag
</t>
<t>
fragment
</t>
<t>
header line
</t>
<t>
message body
</t>
<t>
method
</t>
<t>
path
</t>
<t>
query
</t>
<t>
request URI
</t>
<t>
response body
</t>
</list>
</t>
</section>
<section title="YANG">
<t>
The following terms are defined in <xref target="RFC6020"/>:
</t>
<t>
<list style="symbols">
<t>
container
</t>
<t>
data node
</t>
<t>
key leaf
</t>
<t>
leaf
</t>
<t>
leaf-list
</t>
<t>
list
</t>
<t>
presence container (or P-container)
</t>
<t>
RPC operation (now called protocol operation)
</t>
<t>
non-presence container (or NP-container)
</t>
<t>
ordered-by system
</t>
<t>
ordered-by user
</t>
</list>
</t>
</section>
<section title="RESTCONF">
<t>
The following terms are defined in <xref target="I-D.ietf-netconf-restconf"/>:
</t>
<t>
<list style="symbols">
<t>
data resource
</t>
<t>
datastore resource
</t>
<t>
patch
</t>
<t>
RESTCONF capability
</t>
<t>
target resource
</t>
</list>
</t>
</section>
<section title="YANG Patch">
<t>
The following terms are used within this document:
</t>
<t>
<list style="symbols">
<t>
YANG Patch: a conceptual edit request using the "yang‑patch"
YANG container, defined in <xref target="module"/>.
In HTTP, refers to a PATCH method where the media type
is "application/yang.patch+xml" or "application/yang.patch+json".
</t>
<t>
YANG Patch Status: a conceptual edit status response using
the YANG "yang‑patch‑status" container, defined in <xref target="module"/>.
In HTTP, refers to a response message for a PATCH method,
where the message body is identified by the media
type "application/yang.patch‑status+xml"
or "application/yang.patch‑status+json".
</t>
</list>
</t>
</section>
<section title="Tree Diagrams">
<t>
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these
diagrams is as follows:
</t>
<t>
<list style="symbols">
<t>
Brackets "[" and "]" enclose list keys.
</t>
<t>
Abbreviations before data node names: "rw" means configuration
(read-write) and "ro" state data (read-only).
</t>
<t>
Symbols after data node names: "?" means an optional node and "*"
denotes a "list" and "leaf‑list".
</t>
<t>
Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
</t>
<t>
Ellipsis ("...") stands for contents of subtrees that are not shown.
</t>
</list>
</t>
</section>
</section>
</section>
<section title="YANG Patch" anchor="yang-patch">
<t>
A "YANG Patch" is an ordered list of edits that are applied
to the target datastore by the server. The specific fields
are defined in the YANG module in <xref target="module"/>.
</t>
<t>
For RESTCONF, the YANG Patch operation is invoked
by the client by sending a PATCH method request with
the YANG Patch media type. A message body representing the
YANG Patch input parameters MUST be provided.
</t>
<t>
The RESTCONF server MUST return the Accept-Patch header
in an OPTIONS response, as specified in <xref target="RFC5789"/>,
which includes the media type for YANG Patch.
</t>
<t>
Example:
</t>
<figure>
<artwork><![CDATA[
Accept-Patch: application/yang.patch
]]></artwork>
</figure>
<section title="Target Resource">
<t>
The YANG Patch operation uses a conceptual root within
a NETCONF configuration datastore to identity the patch point for
the edit operation. This root can be the datastore itself, or
1 or more data nodes within the datastore.
</t>
<t>
For RESTCONF, the target resource is derived from the request URI.
</t>
</section>
<section title="yang-patch Input">
<t>
A YANG patch is optionally identified by a unique "patch‑id" and it
may have an optional comment. A patch is an ordered collection of
edits. Each edit is identified by an "edit‑id" and it has an edit
operation (create, delete, insert, merge, move, replace, remove)
that is applied to the target resource. Each edit can be applied
to a sub-resource "target" within the target resource.
If the operation is "insert" or "move", then the "where"
parameter indicates how the node is inserted or moved.
For values "before" and "after", the "point" parameter
specifies the data node insertion point.
</t>
<t>
A data element representing the YANG Patch is sent
by the client to specify the edit operation request.
When used with the HTTP PATCH method, this data is identified
by the YANG Patch media type.
</t>
<t>
YANG Tree Diagram For "yang‑patch" Container
</t>
<figure>
<artwork><![CDATA[
+--rw yang-patch
+--rw patch-id? string
+--rw comment? string
+--rw edit [edit-id]
+--rw edit-id string
+--rw operation enumeration
+--rw target target-resource-offset
+--rw point? target-resource-offset
+--rw where? enumeration
+--rw value
]]></artwork>
</figure>
</section>
<section title="yang-patch-status Output">
<t>
A data element representing the YANG Patch Status is returned
to the client to report the detailed status of the edit operation.
When used with the HTTP PATCH method, this data is identified
by the YANG Patch Status media type, and the syntax specification
is defined in <xref target="module"/>.
</t>
<t>
YANG Tree Diagram For "yang‑patch‑status" Container:
</t>
<figure>
<artwork><![CDATA[
+--rw yang-patch-status
+--rw patch-id? string
+--rw (global-status)?
| +--:(global-errors)
| | +--ro errors
| |
| +--:(ok)
| +--rw ok? empty
+--rw edit-status
+--rw edit [edit-id]
+--rw edit-id string
+--rw (edit-status-choice)?
+--:(ok)
| +--rw ok? empty
+--:(errors)
+--ro errors
]]></artwork>
</figure>
</section>
<section title="Target Data Node">
<t>
The target data node for each edit operation is determined
by the value of the target resource in the request and the
"target" leaf within each "edit" entry.
</t>
<t>
If the target resource specified in the request URI identifies
a datastore resource, then the path string in the "target" leaf
is an absolute path expression. The first node specified
in the "target" leaf is a top-level data node defined within
a YANG module.
</t>
<t>
If the target resource specified in the request URI identifies
a data resource, then the path string in the "target" leaf
is a relative path expression. The first node specified
in the "target" leaf is a child node of the data node associated
with the target resource.
</t>
</section>
<section title="Edit Operations">
<t>
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.
</t>
<?rfc compact="yes"?><texttable title="YANG Patch Edit Operations">
<ttcol align='left'> Operation</ttcol>
<ttcol align='left'>Description</ttcol>
<c>create</c>
<c>create a new data resource if it does not already exist or error</c>
<c>delete</c>
<c>delete a data resource if it already exists or error</c>
<c>insert</c>
<c>insert a new user-ordered data resource</c>
<c>merge</c>
<c>merge the edit value with the target data resource; create if it does not already exist</c>
<c>move</c>
<c>re-order the target data resource</c>
<c>replace</c>
<c>replace the target data resource with the edit value</c>
<c>remove</c>
<c>remove a data resource if it already exists or no error</c>
</texttable>
<?rfc compact="no"?></section>
<section title="Error Handling">
<t>
If a well-formed, schema-valid YANG Patch message is received, then
the server will process the supplied edits in ascending order.
The following error modes apply to the processing of this edit list:
</t>
<t>
All the specified edits MUST be applied or the
target datastore contents MUST be returned to its original state
before the PATCH method started.
</t>
<t>
The server will save the running datastore to non-volatile storage
if it has changed, after the edits have been successfully completed.
</t>
</section>
<section title="yang-patch RESTCONF Capability">
<t>
A URI is defined to identify the YANG Patch extension to
the base RESTCONF protocol. If the server supports the
YANG Patch media type, then the "yang‑patch" RESTCONF capability
defined in <xref target="capability-uri-def"/> MUST be present in the
"capability" leaf-list in the
"ietf‑restconf‑monitoring" module defined in <xref target="I-D.ietf-netconf-restconf"/>.
</t>
</section>
</section>
<section title="YANG Module" anchor="module">
<t>
The "ietf‑yang‑patch" module defines conceptual definitions
with the 'restconf‑media‑type' extension statements,
which are not meant to be implemented
as datastore contents by a server.
</t>
<t>
The "ietf‑restconf" module from <xref target="I-D.ietf-netconf-restconf"/>
is used by this module for the 'restconf‑media‑type'
extension definition.
</t>
<t>
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
</t>
<t><CODE BEGINS> file "ietf-yang-patch@2015-04-30.yang"</t>
<figure>
<artwork><![CDATA[
module ietf-yang-patch {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch";
prefix "ypatch";
import ietf-yang-types { prefix yang; }
import ietf-restconf {
prefix rc;
revision-date 2015-06-04;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Mahesh Jethanandani
<mailto:mjethanandani@gmail.com>
Editor: Andy Bierman
<mailto:andy@yumaworks.com>
Editor: Martin Bjorklund
<mailto:mbj@tail-f.com>
Editor: Kent Watsen
<mailto:kwatsen@juniper.net>";
description
"This module contains conceptual YANG specifications
for the YANG Patch and YANG Patch Status data structures.
Note that the YANG definitions within this module do not
represent configuration data of any kind.
The YANG grouping statements provide a normative syntax
for XML and JSON message encoding purposes.
Copyright (c) 2015 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
// RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-yang-patch-04.txt
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
revision 2015-06-04 {
description
"Initial revision.";
reference
"RFC XXXX: YANG Patch Media Type.";
}
typedef target-resource-offset {
type yang:xpath1.0;
description
"Contains an XPath absolute path expression identifying
a sub-resource within the target resource.
The document root for this XPath expression is the
target resource that is specified in the
protocol operation (e.g., the URI for the PATCH request).";
}
rc:restconf-media-type "application/yang.patch" {
uses yang-patch;
}
rc:restconf-media-type "application/yang.patch-status" {
uses yang-patch-status;
}
grouping yang-patch {
description
"A grouping that contains a YANG container
representing the syntax and semantics of a
YANG Patch edit request message.";
container yang-patch {
description
"Represents a conceptual sequence of datastore edits,
called a patch. Each patch is given a client-assigned
patch identifier. Each edit MUST be applied
in ascending order, and all edits MUST be applied.
If any errors occur, then the target datastore MUST NOT
be changed by the patch operation.
YANG datastore validation (defined in RFC 6020, section
8.3.3) is performed before any edits have been applied
to the running datastore.
It is possible for a datastore constraint violation to occur
due to any node in the datastore, including nodes not
included in the edit list. Any validation errors MUST
be reported in the reply message.";
reference
"RFC 6020, section 8.3.";
leaf patch-id {
type string;
description
"An arbitrary string provided by the client to identify
the entire patch. This value SHOULD be present in any
audit logging records generated by the server for the
patch. Error messages returned by the server pertaining
to this patch will be identified by this patch-id value.";
}
leaf comment {
type string;
description
"An arbitrary string provided by the client to describe
the entire patch. This value SHOULD be present in any
audit logging records generated by the server for the
patch.";
}
list edit {
key edit-id;
ordered-by user;
description
"Represents one edit within the YANG Patch
request message. The edit list is applied
in the following manner:
- The first edit is conceptually applied to a copy
of the existing target datastore, e.g., the
running configuration datastore.
- Each ascending edit is conceptually applied to
the result of the previous edit(s).
- After all edits have been successfully processed,
the result is validated according to YANG constraints.
- If successful, the server will attempt to apply
the result to the target datastore. ";
leaf edit-id {
type string;
description
"Arbitrary string index for the edit.
Error messages returned by the server pertaining
to a specific edit will be identified by this
value.";
}
leaf operation {
type enumeration {
enum create {
description
"The target data node is created using the
supplied value, only if it does not already
exist.";
}
enum delete {
description
"Delete the target node, only if the data resource
currently exists, otherwise return an error.";
}
enum insert {
description
"Insert the supplied value into a user-ordered
list or leaf-list entry. The target node must
represent a new data resource. If the 'where'
parameter is set to 'before' or 'after', then
the 'point' parameter identifies the insertion
point for the target node.";
}
enum merge {
description
"The supplied value is merged with the target data
node.";
}
enum move {
description
"Move the target node. Reorder a user-ordered
list or leaf-list. The target node must represent
an existing data resource. If the 'where' parameter
is set to 'before' or 'after', then the 'point'
parameter identifies the insertion point to move
the target node.";
}
enum replace {
description
"The supplied value is used to replace the target
data node.";
}
enum remove {
description
"Delete the target node if it currently exists.";
}
}
mandatory true;
description
"The datastore operation requested for the associated
edit entry";
}
leaf target {
type target-resource-offset;
mandatory true;
description
"Identifies the target data resource for the edit
operation.";
}
leaf point {
when "(../operation = 'insert' or " +
"../operation = 'move') and " +
"(../where = 'before' or ../where = 'after')" {
description
"Point leaf only applies for insert or move
operations, before or after an existing entry.";
}
type target-resource-offset;
description
"The absolute URL path for the data node that is being
used as the insertion point or move point for the
target of this edit entry.";
}
leaf where {
when "../operation = 'insert' or ../operation = 'move'" {
description
"Where leaf only applies for insert or move
operations.";
}
type enumeration {
enum before {
description
"Insert or move a data node before the data resource
identified by the 'point' parameter.";
}
enum after {
description
"Insert or move a data node after the data resource
identified by the 'point' parameter.";
}
enum first {
description
"Insert or move a data node so it becomes ordered
as the first entry.";
}
enum last {
description
"Insert or move a data node so it becomes ordered
as the last entry.";
}
}
default last;
description
"Identifies where a data resource will be inserted or
moved. YANG only allows these operations for
list and leaf-list data nodes that are ordered-by
user.";
}
anyxml value {
when "(../operation = 'create' or " +
"../operation = 'merge' " +
"or ../operation = 'replace' or " +
"../operation = 'insert')" {
description
"Value node only used for create, merge,
replace, and insert operations";
}
description
"Value used for this edit operation.
The anyxml value MUST represent a container with
exactly one child node, which MUST identify the
target resource associated with the 'target' leaf.
For example, suppose the target node is a YANG container
named foo:
container foo {
leaf a { type string; }
leaf b { type int32; }
}
The value node will contain one instance of foo:
<value>
<foo xmlns='example-foo-namespace'>
<a>some value</a>
<b>42</b>
</foo>
</value>
";
}
}
}
} // grouping yang-patch
grouping yang-patch-status {
description
"A grouping that contains a YANG container
representing the syntax and semantics of
YANG Patch status response message.";
container yang-patch-status {
description
"A container representing the response message
sent by the server after a YANG Patch edit
request message has been processed.";
leaf patch-id {
type string;
description
"The patch-id value used in the request";
}
choice global-status {
description
"Report global errors or complete success.
If there is no case selected then errors
are reported in the edit-status container.";
case global-errors {
uses rc:errors;
description
"This container will be present if global
errors unrelated to a specific edit occurred.";
}
leaf ok {
type empty;
description
"This leaf will be present if the request succeeded
and there are no errors reported in the edit-status
container.";
}
}
container edit-status {
description
"This container will be present if there are
edit-specific status responses to report.
If all edits succeeded and the 'global-status'
returned is 'ok', then a server MAY omit this
container";
list edit {
key edit-id;
description
"Represents a list of status responses,
corresponding to edits in the YANG Patch
request message. If an edit entry was
skipped or not reached by the server,
then this list will not contain a corresponding
entry for that edit.";
leaf edit-id {
type string;
description
"Response status is for the edit list entry
with this edit-id value.";
}
choice edit-status-choice {
description
"A choice between different types of status
responses for each edit entry.";
leaf ok {
type empty;
description
"This edit entry was invoked without any
errors detected by the server associated
with this edit.";
}
case errors {
uses rc:errors;
description
"The server detected errors associated with the
edit identified by the same edit-id value.";
}
}
}
}
}
} // grouping yang-patch-status
}
]]></artwork>
</figure>
<t><CODE ENDS></t>
</section>
<section title="IANA Considerations" anchor="iana">
<section title="YANG Module Registry">
<t>
This document registers one URI in the IETF XML registry
<xref target="RFC3688"/>. Following the format in RFC 3688, the following
registration is requested to be made.
</t>
<figure>
<artwork><![CDATA[
URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch
Registrant Contact: The NETMOD WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
]]></artwork>
</figure>
<t>
This document registers one YANG module in the YANG Module Names
registry <xref target="RFC6020"/>.
</t>
<figure>
<artwork><![CDATA[
name: ietf-yang-patch
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch
prefix: ypatch
// RFC Ed.: replace XXXX with RFC number and remove this note
reference: RFC XXXX
]]></artwork>
</figure>
</section>
<section title="application/yang.patch Media Types">
<t>
The MIME media type for a YANG Patch document is application/yang.patch.
</t>
<figure>
<artwork><![CDATA[
Type name: application
Subtype name: yang.patch
Required parameters: none
Optional parameters: none
Encoding considerations: 8-bit
Security considerations: See Section 5 of RFC XXXX
Interoperability considerations: none
// RFC Ed.: replace XXXX with RFC number and remove this note
Published specification: RFC XXXX
]]></artwork>
</figure>
</section>
<section title="application/yang.patch-status Media Types">
<t>
The MIME media type for a YANG Patch status
document is application/yang.patch-status.
</t>
<figure>
<artwork><![CDATA[
Type name: application
Subtype name: yang.patch-status
Required parameters: none
Optional parameters: none
Encoding considerations: 8-bit
Security considerations: See Section 5 of RFC XXXX
Interoperability considerations: none
// RFC Ed.: replace XXXX with RFC number and remove this note
Published specification: RFC XXXX
]]></artwork>
</figure>
</section>
<section title="RESTCONF Capability URNs" anchor="capability-uri-def">
<t>
This document registers one capability identifier in
"RESTCONF Protocol Capability URNs" registry
</t>
<figure>
<artwork><![CDATA[
Index
Capability Identifier
------------------------
:yang-patch
urn:ietf:params:restconf:capability:yang-patch:1.0
]]></artwork>
</figure>
</section>
</section>
<section title="Security Considerations">
<t>
The YANG Patch media type does not introduce any significant
new security threats, beyond what is described in
<xref target="I-D.ietf-netconf-restconf"/>.
This document defines edit processing instructions for a
variant of the PATCH method, as used within the RESTCONF protocol.
</t>
<t>
It is important for server implementations to carefully
validate all the edit request parameters in some manner.
If the entire YANG Patch request cannot be completed,
then no configuration changes to the system are done.
</t>
<t>
A server implementation SHOULD attempt to prevent
system disruption due to partial processing of the
YANG Patch edit list. It may be possible to construct
an attack on such a server, which relies on the
edit processing order mandated by YANG Patch.
</t>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="RFC2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="S. Bradner">
<organization>Harvard University</organization>
</author>
<date month="March" year="1997"/>
<abstract>
<t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<format type="TXT" octets="4723" target="ftp://ftp.isi.edu/in-notes/rfc2119.txt"/>
</reference>
<reference anchor="RFC2616">
<front>
<title abbrev="HTTP/1.1">Hypertext Transfer Protocol -- HTTP/1.1</title>
<author initials="R." surname="Fielding" fullname="Roy T. Fielding">
<organization abbrev="UC Irvine">Department of Information and Computer Science</organization>
<address>
<postal>
<street>University of California, Irvine</street>
<city>Irvine</city>
<region>CA</region>
<code>92697-3425</code></postal>
<facsimile>+1(949)824-1715</facsimile>
<email>fielding@ics.uci.edu</email></address></author>
<author initials="J." surname="Gettys" fullname="James Gettys">
<organization abbrev="Compaq/W3C">World Wide Web Consortium</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>545 Technology Square</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code></postal>
<facsimile>+1(617)258-8682</facsimile>
<email>jg@w3.org</email></address></author>
<author initials="J." surname="Mogul" fullname="Jeffrey C. Mogul">
<organization abbrev="Compaq">Compaq Computer Corporation</organization>
<address>
<postal>
<street>Western Research Laboratory</street>
<street>250 University Avenue</street>
<city>Palo Alto</city>
<region>CA</region>
<code>94305</code></postal>
<email>mogul@wrl.dec.com</email></address></author>
<author initials="H." surname="Frystyk" fullname="Henrik Frystyk Nielsen">
<organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>545 Technology Square</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code></postal>
<facsimile>+1(617)258-8682</facsimile>
<email>frystyk@w3.org</email></address></author>
<author initials="L." surname="Masinter" fullname="Larry Masinter">
<organization abbrev="Xerox">Xerox Corporation</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>3333 Coyote Hill Road</street>
<city>Palo Alto</city>
<region>CA</region>
<code>94034</code></postal>
<email>masinter@parc.xerox.com</email></address></author>
<author initials="P." surname="Leach" fullname="Paul J. Leach">
<organization abbrev="Microsoft">Microsoft Corporation</organization>
<address>
<postal>
<street>1 Microsoft Way</street>
<city>Redmond</city>
<region>WA</region>
<code>98052</code></postal>
<email>paulle@microsoft.com</email></address></author>
<author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
<organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>545 Technology Square</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code></postal>
<facsimile>+1(617)258-8682</facsimile>
<email>timbl@w3.org</email></address></author>
<date year="1999" month="June"/>
<abstract>
<t>
The Hypertext Transfer Protocol (HTTP) is an application-level
protocol for distributed, collaborative, hypermedia information
systems. It is a generic, stateless, protocol which can be used for
many tasks beyond its use for hypertext, such as name servers and
distributed object management systems, through extension of its
request methods, error codes and headers . A feature of HTTP is
the typing and negotiation of data representation, allowing systems
to be built independently of the data being transferred.
</t>
<t>
HTTP has been in use by the World-Wide Web global information
initiative since 1990. This specification defines the protocol
referred to as "HTTP/1.1", and is an update to RFC 2068 .
</t></abstract></front>
<seriesInfo name="RFC" value="2616"/>
<format type="TXT" octets="422317" target="http://www.rfc-editor.org/rfc/rfc2616.txt"/>
<format type="PS" octets="5529857" target="http://www.rfc-editor.org/rfc/rfc2616.ps"/>
<format type="PDF" octets="550558" target="http://www.rfc-editor.org/rfc/rfc2616.pdf"/>
<format type="HTML" octets="636125" target="http://xml.resource.org/public/rfc/html/rfc2616.html"/>
<format type="XML" octets="493420" target="http://xml.resource.org/public/rfc/xml/rfc2616.xml"/>
</reference>
<reference anchor='RFC3688'>
<front>
<title>The IETF XML Registry</title>
<author initials='M.' surname='Mealling' fullname='M. Mealling'>
<organization /></author>
<date year='2004' month='January' />
<abstract>
<t>This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas.</t></abstract></front>
<seriesInfo name='BCP' value='81' />
<seriesInfo name='RFC' value='3688' />
<format type='TXT' octets='17325' target='http://www.rfc-editor.org/rfc/rfc3688.txt' />
</reference>
<reference anchor="RFC5789">
<front>
<title>PATCH Method for HTTP</title>
<author initials="L." surname="Dusseault" fullname="L. Dusseault">
<organization/></author>
<author initials="J." surname="Snell" fullname="J. Snell">
<organization/></author>
<date year="2010" month="March"/>
<abstract>
<t>Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name="RFC" value="5789"/>
<format type="TXT" octets="21706" target="http://www.rfc-editor.org/rfc/rfc5789.txt"/>
</reference>
<!--
<reference anchor='RFC5785'>
<front>
<title>Defining Well-Known Uniform Resource Identifiers (URIs)</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'>
<organization /></author>
<author initials='E.' surname='Hammer-Lahav' fullname='E. Hammer-Lahav'>
<organization /></author>
<date year='2010' month='April' />
<abstract>
<t>This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name='RFC' value='5785' />
<format type='TXT' octets='13779' target='http://www.rfc-editor.org/rfc/rfc5785.txt' />
</reference>
-->
<reference anchor='RFC6241'>
<front>
<title>Network Configuration Protocol (NETCONF)</title>
<author initials='R.' surname='Enns' fullname='R. Enns' role="editor">
<organization/>
</author>
<author initials='M.' surname='Bjorklund' fullname='M. Bjorklund' role="editor">
<organization/>
</author>
<author initials='J.' surname='Schoenwaelder' fullname='J. Schoenwaelder' role="editor">
<organization/>
</author>
<author initials='A.' surname='Bierman' fullname='A. Bierman' role="editor">
<organization/>
</author>
<date year='2011' month='June'/>
</front>
<seriesInfo name='RFC' value='6241'/>
</reference>
<reference anchor="RFC6020">
<front>
<title>YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)</title>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/>
</author>
<date year="2010" month="October"/>
<abstract>
<t>YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS TRACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6020"/>
<format type="TXT" octets="324178" target="http://www.rfc-editor.org/rfc/rfc6020.txt"/>
</reference>
<!--
<reference anchor="RFC6536">
<front>
<title>Network Configuration Protocol (NETCONF) Access Control Model</title>
<author initials="A." surname="Bierman" fullname="A. Bierman">
<organization/></author>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/></author>
<date year="2012" month="March"/>
<abstract>
<t>The standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) requires a structured and secure operating environment that promotes human usability and multi-vendor interoperability. There is a need for standard mechanisms to restrict NETCONF protocol access for particular users to a pre-configured subset of all available NETCONF protocol operations and content. This document defines such an access control model. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name="RFC" value="6536"/>
<format type="TXT" octets="90803" target="http://www.rfc-editor.org/rfc/rfc6536.txt"/>
</reference>
-->
<!--
<reference anchor='RFC6991'>
<front>
<title>Common YANG Data Types</title>
<author initials='J.' surname='Schoenwaelder' fullname='J. Schoenwaelder'>
<organization /></author>
<date year='2013' month='July' />
<abstract>
<t>This document introduces a collection of common data types to be used with the YANG data modeling language. This document obsoletes RFC 6021.</t></abstract></front>
<seriesInfo name='RFC' value='6991' />
<format type='TXT' octets='60242' target='http://www.rfc-editor.org/rfc/rfc6991.txt' />
</reference>
-->
<reference anchor="I-D.ietf-netconf-restconf">
<front>
<title>RESTCONF Protocol</title>
<author initials="A." surname="Bierman" fullname="A. Bierman">
<organization>YumaWorks</organization>
</author>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization>Tail-f Systems</organization>
</author>
<author initials="K." surname="Watsen" fullname="K. Watsen">
<organization>Juniper Networks</organization>
</author>
<date year="2015" month="July"/>
</front>
<seriesInfo name="Internet-Draft"
value="draft-ietf-netconf-restconf-07"/>
<format type='TXT'
target='http://www.ietf.org/id/draft-ietf-netconf-restconf-07.txt'/>
</reference>
<!-- END RESTCONF -->
<reference anchor="RFC7158">
<front>
<title>
The JavaScript Object Notation (JSON) Data Interchange Format
</title>
<author initials="T." surname="Bray"
fullname="T. Bray" role="editor">
<organization />
</author>
<date month="March" year="2013" />
</front>
<seriesInfo name="RFC" value="7158" />
<format type="TXT"
target="http://www.rfc-editor.org/rfc/rfc7158.txt"/>
</reference>
<reference anchor='W3C.REC-xml-20081126'
target='http://www.w3.org/TR/2008/REC-xml-20081126'>
<front>
<title>Extensible Markup Language (XML) 1.0 (Fifth Edition)</title>
<author initials='F.' surname='Yergeau' fullname='François Yergeau'>
<organization />
</author>
<author initials='E.' surname='Maler' fullname='Eve Maler'>
<organization />
</author>
<author initials='J.' surname='Paoli' fullname='Jean Paoli'>
<organization />
</author>
<author initials='C.' surname='Sperberg-McQueen' fullname='C. M. Sperberg-McQueen'>
<organization />
</author>
<author initials='T.' surname='Bray' fullname='Tim Bray'>
<organization />
</author>
<date month='November' day='26' year='2008' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation' value='REC-xml-20081126' />
<format type='HTML' target='http://www.w3.org/TR/2008/REC-xml-20081126' />
</reference>
</references>
<section title="Acknowledgements">
<t>
The authors would like to thank the following people for
their contributions to this document: Rex Fernando.
</t>
</section>
<section title="Change Log">
<figure>
<artwork><![CDATA[
-- RFC Ed.: remove this section before publication.
]]></artwork>
</figure>
<t>
The YANG Patch issue tracker can be found here:
https://github.com/netconf-wg/yang-patch/issues
</t>
<section title="04 to 05">
<t>
<list style="symbols">
<t>
updated reference to RESTCONF
</t>
</list>
</t>
</section>
<section title="03 to 04">
<t>
<list style="symbols">
<t>
removed NETCONF specific text
</t>
<t>
changed data-resource-offset typedef from a relative URI
to an XPath absolute path expression
</t>
<t>
clarified insert operation
</t>
<t>
removed requirement that edits MUST be applied in ascending order
</t>
<t>
change SHOULD keep datastore unchanged on error
to MUST (this is required by HTTP PATCH)
</t>
<t>
removed length restriction on 'comment' leaf
</t>
<t>
updated YANG tree for example-jukebox library
</t>
</list>
</t>
</section>
<section title="02 to 03">
<t>
<list style="symbols">
<t>
added usage of restconf-media-type extension to map
the yang-patch and yang-patch-status groupings
to media types
</t>
<t>
added yang-patch RESTCONF capability URI
</t>
<t>
Added sub-section for terms used from RESTCONF
</t>
<t>
filled in security considerations section
</t>
</list>
</t>
</section>
<section title="01 to 02">
<t>
<list style="symbols">
<t>
Reversed order of change log
</t>
<t>
Clarified anyxml structure of "value" parameter within
a YANG patch request (github issue #1)
</t>
<t>
Updated RESTCONF reference
</t>
<t>
Added note to open issues section to check github instead
</t>
</list>
</t>
</section>
<section title="00 to 01">
<t>
<list style="symbols">
<t>
Added text requiring support for Accept-Patch header,
and removed 'Identification of YANG Patch capabilities' open
issue.
</t>
<t>
Removed 'location' leaf from yang-patch-status grouping
</t>
<t>
Removed open issue 'Protocol independence' because the
location leaf was removed.
</t>
<t>
Removed open issue 'RESTCONF coupling' because there is no
concern about a normative reference to RESTCONF.
There may need to be a YANG 1.1 mechanism to allow protocol
template usage (instead of grouping wrapper).
</t>
<t>
Removed open issue 'Is the delete operation needed'.
It was decided that both delete and remove should remain
as operations and clients can choose which one to use.
This is not an implementation burden on the server.
</t>
<t>
Removed open issue 'global-errors needed'.
It was decided that they are needed as defined
because the global <ok/> is needed and the special
key value for edit=global error only allows for 1 global error.
</t>
<t>
Removed open issue 'Is location leaf needed'.
It was decided that it is not needed so this leaf has been removed.
</t>
<t>
Removed open issue 'Bulk editing support in yang-patch-status'.
The 'location' leaf has been removed so this issue is no longer
applicable.
</t>
<t>
Removed open issue 'Edit list mechanism'.
Added text to the 'edit' list description-stmt
about how the individual edits must be processed.
There is no concern about duplicate edits which cause
intermediate results to be altered by subsequent edits
in the same edit list.
</t>
</list>
</t>
</section>
<section title="bierman:yang-patch-00 to ietf:yang-patch-00">
<t>
<list style="symbols">
<t>
Created open issues section
</t>
</list>
</t>
</section>
</section>
<section title="Open Issues">
<figure>
<artwork><![CDATA[
-- RFC Ed.: remove this section before publication.
]]></artwork>
</figure>
<t>
Refer to the github issue tracker for any open issues:
</t>
<figure>
<artwork><![CDATA[
https://github.com/netconf-wg/yang-patch/issues
]]></artwork>
</figure>
</section>
<section title="Example YANG Module">
<t>
The example YANG module used in this document represents
a simple media jukebox interface. The "example‑jukebox"
YANG module is defined in <xref target="I-D.ietf-netconf-restconf"/>.
</t>
<t>
YANG Tree Diagram for "example‑jukebox" Module:
</t>
<figure>
<artwork><![CDATA[
+--rw jukebox!
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id leafref
+--rw player
+--rw gap? decimal64
]]></artwork>
</figure>
<figure>
<artwork><![CDATA[
rpcs:
]]></artwork>
</figure>
<figure>
<artwork><![CDATA[
+---x play
+--ro input
+--ro playlist string
+--ro song-number uint32
]]></artwork>
</figure>
<section title="YANG Patch Examples">
<t>
This section includes RESTCONF examples.
Most examples are shown in JSON encoding <xref target="RFC7158"/>, and some
are shown in XML encoding <xref target="W3C.REC-xml-20081126"/>.
</t>
<section title="Add Resources: Error">
<t>
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.
</t>
<figure>
<artwork><![CDATA[
Request from client:
PATCH /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang.patch-status+json
Content-Type: application/yang.patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "add-songs-patch",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/song",
"value" : {
"song" : {
"name" : "Bridge Burning",
"location" : "/media/bridge_burning.mp3",
"format" : "MP3",
"length" : 288
}
}
},
{
"edit-id" : "edit2",
"operation" : "create",
"target" : "/song",
"value" : {
"song" : {
"name" : "Rope",
"location" : "/media/rope.mp3",
"format" : "MP3",
"length" : 259
}
}
},
{
"edit-id" : "edit3",
"operation" : "create",
"target" : "/song",
"value" : {
"song" : {
"name" : "Dear Rosemary",
"location" : "/media/dear_rosemary.mp3",
"format" : "MP3",
"length" : 269
}
}
}
]
}
}
Response from server:
HTTP/1.1 409 Conflict
Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
Content-Type: application/yang.patch-status+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch",
"edit-status" : {
"edit" : [
{
"edit-id" : "edit1",
"errors" : {
"error" : [
{
"error-type": "application",
"error-tag": "data-exists",
"error-path": "/example-jukebox:jukebox/library
/artist=Foo%20Fighters/album=Wasting%20Light
/song=Burning%20Light",
"error-message":
"Data already exists, cannot be created"
}
]
}
}
]
}
}
}
]]></artwork>
</figure>
</section>
<section title="Add Resources: Success">
<t>
The following example shows several songs being added to
an existing album.
</t>
<t>
<list style="symbols">
<t>
Each of 2 edits contains one song.
</t>
<t>
Both edits succeed and new sub-resources are created
</t>
</list>
</t>
<figure>
<artwork><![CDATA[
Request from client:
PATCH /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album=Wasting%20Light
HTTP/1.1
Host: example.com
Accept: application/yang.patch-status+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",
"value" : {
"song" : {
"name" : "Rope",
"location" : "/media/rope.mp3",
"format" : "MP3",
"length" : 259
}
}
},
{
"edit-id" : "edit2",
"operation" : "create",
"target" : "/song",
"value" : {
"song" : {
"name" : "Dear Rosemary",
"location" : "/media/dear_rosemary.mp3",
"format" : "MP3",
"length" : 269
}
}
}
]
}
}
Response from server:
HTTP/1.1 200 Success
Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
Content-Type: application/yang.patch-status+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch-2",
"ok" : [null]
}
}
]]></artwork>
</figure>
</section>
<section title="Move list entry example">
<t>
The following example shows a song being moved within
an existing playlist. Song "1" in playlist "Foo‑One" is
being moved after song "3" in the playlist.
The operation succeeds, so a non-error reply example can be shown.
</t>
<figure>
<artwork><![CDATA[
Request from client:
PATCH /restconf/data/example-jukebox:jukebox/
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang.patch-status+json
Content-Type: application/yang.patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "move-song-patch",
"comment" : "Move song 1 after song 3",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "move",
"target" : "/song/1",
"point" : "/song3",
"where" : "after"
}
]
}
}
Response from server:
HTTP/1.1 400 OK
Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
Content-Type: application/yang.patch-status+json
{
"ietf-restconf:yang-patch-status" : {
"patch-id" : "move-song-patch",
"ok" : [null]
}
}
]]></artwork>
</figure>
</section>
</section>
</section>
</back></rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 02:47:40 |