YANG Patch Media TypeYumaWorksandy@yumaworks.comTail-f Systemsmbj@tail-f.comJuniper Networkskwatsen@juniper.netCiscorex@cisco.com
This document describes a method for applying patches
to NETCONF datastores using data defined with the YANG
data modeling language.
There is a need for standard mechanisms to patch NETCONF
datastores which contain conceptual data that conforms to
schema specified with YANG . 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.
This document defines a media type for a YANG-based editing
mechanism that can be used with the HTTP PATCH method
or custom NETCONF operations (defined with the YANG rpc-stmt).
YANG Patch is designed to support multiple protocols
with the same mechanisms. The RESTCONF protocol
utilizes YANG Patch with the HTTP PATCH method. A new RPC
operation can be defined to utilize YANG Patch in the NETCONF protocol.
Both the RESTCONF and NETCONF protocols are designed to utilize the YANG
data modeling language to specify content schema modules.
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, .
The following terms are defined in :
candidate configuration datastore
client
configuration data
datastore
configuration datastore
protocol operation
running configuration datastore
server
startup configuration datastore
state data
user
The following terms are defined in :
entity tag
fragment
header line
message body
method
path
query
request URI
response body
The following terms are defined in :
container
data node
key leaf
leaf
leaf-list
list
presence container (or P-container)
RPC operation (now called protocol operation)
non-presence container (or NP-container)
ordered-by system
ordered-by user
The following terms are used within this document:
YANG Patch: a conceptual edit request using the "yang‑patch"
YANG container, defined in .
In HTTP, refers to a PATCH method where the media type
is "application/yang.patch+xml" or "application/yang.patch+json".
YANG Patch Status: a conceptual edit status response using
the YANG "yang‑patch‑status" container, defined in .
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".
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these
diagrams is as follows:
Brackets "[" and "]" enclose list keys.
Abbreviations before data node names: "rw" means configuration
(read-write) and "ro" state data (read-only).
Symbols after data node names: "?" means an optional node and "*"
denotes a "list" and "leaf‑list".
Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
Ellipsis ("...") stands for contents of subtrees that are not shown.
A "YANG Patch" is an ordered list of edits that are applied
to the target datastore by the server. The specific fields
are defined with the 'yang‑patch' container definition in
the YANG module .
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.
For NETCONF, a YANG "rpc" statement must be defined.
The "yang‑patch" grouping MUST be included in
the input parameters and the "yang‑patch‑status" grouping
MUST be included in the output parameters.
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.
For RESTCONF, the target resource is derived from the request URI.
For NETCONF, the target resource MUST be defined as an input
parameter in the YANG "rpc" statement.
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.
YANG Tree Diagram For "yang‑patch" Container
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.
YANG Tree Diagram For "yang‑patch‑status" Container:
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.
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.
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.
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.
OperationDescriptioncreatecreate a new data resource if it does not already exist or errordeletedelete a data resource if it already exists or errorinsertinsert a new user-ordered data resourcemergemerge the edit value with the target data resource; create if it does not already existmovere-order the target data resourcereplacereplace the target data resource with the edit valueremoveremove a data resource if it already exists or no error
If a well-formed, schema-valid YANG Patch message is received, then
then the server will process the supplied edits in ascending order.
The following error modes apply to the processing of this edit list:
All the specified edits MUST be applied or the
target datastore contents SHOULD be returned to its original state
before the PATCH method started. The server MAY fail to restore
the contents of the target datastore completely and with certainty.
It is possible for a rollback to fail or an "undo" operation
to fail.
The server will save the running datastore to non-volatile storage
if it has changed, after the edits have been attempted.
The "ietf‑yang‑patch" module defines conceptual definitions
within groupings, which are not meant to be implemented
as datastore contents by a server.
The "ietf‑yang‑types" and "ietf‑inet_types" modules from
are used by this module for some type definitions.
The "ietf‑restconf" module from
is used by this module for a grouping definition.
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file "ietf-yang-patch@2013-12-21.yang"<CODE ENDS>
This document registers one URI in the IETF XML registry
. Following the format in RFC 3688, the following
registration is requested to be made.
This document registers one YANG module in the YANG Module Names
registry .
The MIME media type for a YANG Patch document is application/yang.patch.
The MIME media type for a YANG Patch status
document is application/yang.patch-status.
TBD
Key words for use in RFCs to Indicate Requirement LevelsHarvard UniversityIn 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.Hypertext Transfer Protocol -- HTTP/1.1Department of Information and Computer ScienceUniversity of California, IrvineIrvineCA92697-3425+1(949)824-1715fielding@ics.uci.eduWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682jg@w3.orgCompaq Computer CorporationWestern Research Laboratory250 University AvenuePalo AltoCA94305mogul@wrl.dec.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682frystyk@w3.orgXerox CorporationMIT Laboratory for Computer Science, NE43-3563333 Coyote Hill RoadPalo AltoCA94034masinter@parc.xerox.comMicrosoft Corporation1 Microsoft WayRedmondWA98052paulle@microsoft.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682timbl@w3.org
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.
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 .
The IETF XML RegistryThis 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.PATCH Method for HTTPSeveral 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]Network Configuration Protocol (NETCONF)YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)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]Common YANG Data TypesThis document introduces a collection of common data types to be used with the YANG data modeling language. This document obsoletes RFC 6021.RESTCONF ProtocolYumaWorksTail-f SystemsJuniper NetworksCiscoThe JSON Data Interchange FormatExtensible Markup Language (XML) 1.0 (Fifth Edition)
Split out from RESTCONF draft
Rewrite HTTP sections to be more generic and apply to NETCONF as well
The example YANG module used in this document represents
a simple media jukebox interface. The "example‑jukebox"
YANG module is defined in .
YANG Tree Diagram for "example‑jukebox" Module:
This section includes RESTCONF examples.
NETCONF examples are TBD.
Most examples are shown in JSON encoding , and some
are shown in XML encoding .
To replace just the "year" field in the "album" resource
(instead of replacing the entire resource),
the client might send a plain patch as follows.
Note that the request URI header line is wrapped
for display purposes only:
If the field is updated, the server might respond:
The XML encoding for the same request might be:
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.
The following example shows several songs being added to
an existing album.
Each of 2 edits contains one song.
Both edits succeed and new sub-resources are created
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.