5.  Messages

   The RESTCONF protocol uses HTTP messages.  A single HTTP message
   corresponds to a single protocol method.  Most messages can perform a
   single task on a single resource, such as retrieving a resource or
   editing a resource.  The exception is the PATCH method, which allows
   multiple datastore edits within a single message.

5.1.  Request URI Structure

   Resources are represented with URIs following the structure for
   generic URIs in [RFC3986].

   A RESTCONF operation is derived from the HTTP method and the request
   URI, using the following conceptual fields:

        <OP> /<restconf>/<path>?<query>

          ^       ^        ^       ^
          |       |        |       |
        method  entry  resource  query

          M       M        O        O

       M=mandatory, O=optional

       where:

         <OP> is the HTTP method
         <restconf> is the RESTCONF root resource
         <path> is the target resource URI
         <query> is the query parameter list

   o  method: the HTTP method identifying the RESTCONF operation
      requested by the client, to act upon the target resource specified
      in the request URI.  RESTCONF operation details are described in
      Section 4.

   o  entry: the root of the RESTCONF API configured on this HTTP
      server, discovered by getting the "/.well-known/host-meta"
      resource, as described in Section 3.1.

   o  resource: the path expression identifying the resource that is
      being accessed by the RESTCONF operation.  If this field is not
      present, then the target resource is the API itself, represented
      by the YANG data template named "yang-api", found in Section 8.

   o  query: the set of parameters associated with the RESTCONF message;
      see Section 3.4 of [RFC3986].  RESTCONF parameters have the
      familiar form of "name=value" pairs.  Most query parameters are
      optional to implement by the server and optional to use by the
      client.  Each optional query parameter is identified by a URI.
      The server MUST list the optional query parameter URIs it supports
      in the "capability" leaf-list defined in Section 9.3.

   There is a specific set of parameters defined, although the server
   MAY choose to support query parameters not defined in this document.
   The contents of any query parameter value MUST be encoded according
   to Section 3.4 of [RFC3986].  Any reserved characters MUST be
   percent-encoded, according to Sections 2.1 and 2.5 of [RFC3986].

   Note that the fragment component is not used by the RESTCONF
   protocol.  The fragment is excluded from the target URI by a server,
   as described in Section 5.1 of [RFC7230].

   When new resources are created by the client, a "Location" header
   field is returned, which identifies the path of the newly created
   resource.  The client uses this exact path identifier to access the
   resource once it has been created.

   The target of a RESTCONF operation is a resource.  The "path" field
   in the request URI represents the target resource for the RESTCONF
   operation.

   Refer to Appendix B for examples of RESTCONF request URIs.

5.2.  Message Encoding

   RESTCONF messages are encoded in HTTP according to [RFC7230].  The
   "utf-8" character set is used for all messages.  RESTCONF message
   content is sent in the HTTP message-body.

   Content is encoded in either JSON or XML format.  A server MUST
   support one of either XML or JSON encoding.  A server MAY support
   both XML and JSON encoding.  A client will need to support both XML
   and JSON to interoperate with all RESTCONF servers.

   XML encoding rules for data nodes are defined in [RFC7950].  The same
   encoding rules are used for all XML content.  JSON encoding rules are
   defined in [RFC7951].  Additional JSON encoding rules for metadata
   are defined in [RFC7952].  This encoding is valid JSON, but it also
   has special encoding rules to identify module namespaces and provide
   consistent type processing of YANG data.

   The request input content encoding format is identified with the
   "Content-Type" header field.  This field MUST be present if a
   message-body is sent by the client.

   The server MUST support the "Accept" header field and the "406 Not
   Acceptable" status-line, as defined in [RFC7231].  The response
   output content encoding formats that the client will accept are
   identified with the "Accept" header field in the request.  If it is
   not specified, the request input encoding format SHOULD be used, or
   the server MAY choose any supported content encoding format.

   If there was no request input, then the default output encoding is
   XML or JSON, depending on server preference.  File extensions encoded
   in the request are not used to identify format encoding.

   A client can determine if the RESTCONF server supports an encoding
   format by sending a request using a specific format in the
   "Content-Type" and/or "Accept" header field.  If the server does not
   support the requested input encoding for a request, then it MUST
   return an error response with a "415 Unsupported Media Type"
   status-line.  If the server does not support any of the requested
   output encodings for a request, then it MUST return an error response
   with a "406 Not Acceptable" status-line.

5.3.  RESTCONF Metadata

   The RESTCONF protocol needs to support the retrieval of the same
   metadata that is used in the NETCONF protocol.  Information about
   default leafs, last-modified timestamps, etc. is commonly used to
   annotate representations of the datastore contents.

   With the XML encoding, the metadata is encoded as attributes in XML,
   according to Section 3.3 of [W3C.REC-xml-20081126].  With the JSON
   encoding, the metadata is encoded as specified in [RFC7952].

   The following examples are based on the example in Appendix B.3.9.
   The "report-all-tagged" mode for the "with-defaults" query parameter
   requires that a "default" attribute be returned for default nodes.
   These examples show that attribute for the "mtu" leaf.

5.3.1.  XML Metadata Encoding Example

      GET /restconf/data/interfaces/interface=eth1
          ?with-defaults=report-all-tagged HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml

   The server might respond as follows:

      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+xml

      <interface
        xmlns="urn:example.com:params:xml:ns:yang:example-interface">
        <name>eth1</name>
        <mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0"
          wd:default="true">1500</mtu>
        <status>up</status>
      </interface>

5.3.2.  JSON Metadata Encoding Example

   Note that RFC 6243 defines the "default" attribute with the
   XML Schema Definition (XSD), not YANG, so the YANG module name has to
   be assigned instead of derived from the YANG module.  The value
   "ietf-netconf-with-defaults" is assigned for JSON metadata encoding.

      GET /restconf/data/interfaces/interface=eth1\
          ?with-defaults=report-all-tagged HTTP/1.1
      Host: example.com
      Accept: application/yang-data+json

   The server might respond as follows:

      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+json

      {
        "example:interface" : [
          {
            "name" : "eth1",
            "mtu" : 1500,
            "@mtu" : {
               "ietf-netconf-with-defaults:default" : true
            },
            "status" : "up"
          }
        ]
      }

5.4.  Return Status

   Each message represents some sort of resource access.  An HTTP
   "status-line" header field is returned for each request.  If a status
   code in the "4xx" range is returned in the status-line, then the
   error information SHOULD be returned in the response, according to
   the format defined in Section 7.1.  If a status code in the "5xx"
   range is returned in the status-line, then the error information MAY
   be returned in the response, according to the format defined in
   Section 7.1.  If a status code in the "1xx", "2xx", or "3xx" range is
   returned in the status-line, then error information MUST NOT be
   returned in the response, since these ranges do not represent error
   conditions.

5.5.  Message Caching

   Since the datastore contents change at unpredictable times, responses
   from a RESTCONF server generally SHOULD NOT be cached.

   The server MUST include a "Cache-Control" header field in every
   response that specifies whether the response should be cached.

   Instead of relying on HTTP caching, the client SHOULD track the
   "ETag" and/or "Last-Modified" header fields returned by the server
   for the datastore resource (or data resource, if the server supports
   it).  A retrieval request for a resource can include the
   "If-None-Match" and/or "If-Modified-Since" header fields, which will
   cause the server to return a "304 Not Modified" status-line if the
   resource has not changed.  The client MAY use the HEAD method to
   retrieve just the message header fields, which SHOULD include the
   "ETag" and "Last-Modified" header fields, if this metadata is
   maintained for the target resource.

   Note that access control can be applied to data resources, such that
   the values in the "Last-Modified" and "ETag" headers maintained for a
   data resource may not be reliable, as described in Section 4.3.

6.  Notifications

   The RESTCONF protocol supports YANG-defined event notifications.  The
   solution preserves aspects of NETCONF event notifications [RFC5277]
   while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203]
   transport strategy.

6.1.  Server Support

   A RESTCONF server MAY support RESTCONF notifications.  Clients may
   determine if a server supports RESTCONF notifications by using the
   HTTP OPTIONS, HEAD, or GET method on the "stream" list.  The server
   does not support RESTCONF notifications if an HTTP error code is
   returned (e.g., a "404 Not Found" status-line).

6.2.  Event Streams

   A RESTCONF server that supports notifications will populate a stream
   resource for each notification delivery service access point.  A
   RESTCONF client can retrieve the list of supported event streams from
   a RESTCONF server using the GET method on the "stream" list.

   The "restconf-state/streams" container definition in the
   "ietf-restconf-monitoring" module (defined in Section 9.3) is used to
   specify the structure and syntax of the conceptual child resources
   within the "streams" resource.

   For example:

   The client might send the following request:

      GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
          streams HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml

   The server might send the following response:

      HTTP/1.1 200 OK
      Content-Type: application/yang-data+xml

      <streams
        xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
         <stream>
            <name>NETCONF</name>
            <description>default NETCONF event stream</description>
            <replay-support>true</replay-support>
            <replay-log-creation-time>\
               2007-07-08T00:00:00Z\
            </replay-log-creation-time>
            <access>
               <encoding>xml</encoding>
               <location>https://example.com/streams/NETCONF\
               </location>
            </access>
            <access>
               <encoding>json</encoding>
               <location>https://example.com/streams/NETCONF-JSON\
               </location>
            </access>
         </stream>

         <stream>
            <name>SNMP</name>
            <description>SNMP notifications</description>
            <replay-support>false</replay-support>
            <access>
               <encoding>xml</encoding>
               <location>https://example.com/streams/SNMP</location>
            </access>
         </stream>
         <stream>
            <name>syslog-critical</name>
            <description>Critical and higher severity</description>
            <replay-support>true</replay-support>
            <replay-log-creation-time>
               2007-07-01T00:00:00Z
            </replay-log-creation-time>
            <access>
               <encoding>xml</encoding>
               <location>\
                 https://example.com/streams/syslog-critical\
               </location>
            </access>
         </stream>
      </streams>

6.3.  Subscribing to Receive Notifications

   RESTCONF clients can determine the URL for the subscription resource
   (to receive notifications) by sending an HTTP GET request for the
   "location" leaf with the "stream" list entry.  The value returned by
   the server can be used for the actual notification subscription.

   The client will send an HTTP GET request for the URL returned by the
   server with the "Accept" type "text/event-stream".

   The server will treat the connection as an event stream, using the
   Server-Sent Events [W3C.REC-eventsource-20150203] transport strategy.

   The server MAY support query parameters for a GET method on this
   resource.  These parameters are specific to each event stream.

   For example:

   The client might send the following request:

      GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
          streams/stream=NETCONF/access=xml/location HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml

   The server might send the following response:

      HTTP/1.1 200 OK
      Content-Type: application/yang-data+xml

      <location
        xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">\
        https://example.com/streams/NETCONF\
      </location>

   The RESTCONF client can then use this URL value to start monitoring
   the event stream:

      GET /streams/NETCONF HTTP/1.1
      Host: example.com
      Accept: text/event-stream
      Cache-Control: no-cache
      Connection: keep-alive

   A RESTCONF client MAY request that the server compress the events
   using the HTTP header field "Accept-Encoding".  For instance:

      GET /streams/NETCONF HTTP/1.1
      Host: example.com
      Accept: text/event-stream
      Cache-Control: no-cache
      Connection: keep-alive
      Accept-Encoding: gzip, deflate

6.3.1.  NETCONF Event Stream

   The server SHOULD support the NETCONF event stream defined in
   Section 3.2.3 of [RFC5277].  The notification messages for this
   stream are encoded in XML.

   The server MAY support additional streams that represent the semantic
   content of the NETCONF event stream, but using a representation with
   a different media type.

   The server MAY support the "start-time", "stop-time", and "filter"
   query parameters, defined in Section 4.8.  Refer to Appendix B.3.6
   for filter parameter examples.

6.4.  Receiving Event Notifications

   RESTCONF notifications are encoded according to the definition of the
   event stream.

   The structure of the event data is based on the <notification>
   element definition in Section 4 of [RFC5277].  It MUST conform to the
   schema for the <notification> element in Section 4 of [RFC5277],
   using the XML namespace as defined in the XSD as follows:

     urn:ietf:params:xml:ns:netconf:notification:1.0

   For JSON-encoding purposes, the module name for the "notification"
   element is "ietf-restconf".

   Two child nodes within the "notification" container are expected,
   representing the event time and the event payload.  The "eventTime"
   node is defined within the same XML namespace as the <notification>
   element.  It is defined to be within the "ietf-restconf" module
   namespace for JSON-encoding purposes.

   The name and namespace of the payload element are determined by the
   YANG module containing the notification-stmt representing the
   notification message.

   In the following example, the YANG module "example-mod" is used:

     module example-mod {
       namespace "http://example.com/event/1.0";
       prefix ex;

       organization "Example, Inc.";
       contact "support at example.com";
       description "Example Notification Data Model Module.";
       revision "2016-07-07" {
         description "Initial version.";
         reference "example.com document 2-9976.";
       }

       notification event {
         description "Example notification event.";
         leaf event-class {
           type string;
           description "Event class identifier.";
         }
         container reporting-entity {
           description "Event specific information.";
           leaf card {
             type string;
             description "Line card identifier.";
           }
         }
         leaf severity {
           type string;
           description "Event severity description.";
         }
       }
     }

   An example SSE event notification encoded using XML:

      data: <notification
      data:    xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
      data:    <eventTime>2013-12-21T00:01:00Z</eventTime>
      data:    <event xmlns="http://example.com/event/1.0">
      data:       <event-class>fault</event-class>
      data:       <reporting-entity>
      data:           <card>Ethernet0</card>
      data:       </reporting-entity>
      data:       <severity>major</severity>
      data:     </event>
      data: </notification>

   An example SSE event notification encoded using JSON:

      data: {
      data:   "ietf-restconf:notification" : {
      data:     "eventTime" : "2013-12-21T00:01:00Z",
      data:     "example-mod:event" : {
      data:       "event-class" : "fault",
      data:       "reporting-entity" : { "card" : "Ethernet0" },
      data:       "severity" : "major"
      data:     }
      data:   }
      data: }

   Alternatively, since neither XML nor JSON is whitespace sensitive,
   the above messages can be encoded onto a single line.  For example:

      XML:

      data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notif\
      ication:1.0"><eventTime>2013-12-21T00:01:00Z</eventTime><event \
      xmlns="http://example.com/event/1.0"><event-class>fault</event-\
      class><reportingEntity><card>Ethernet0</card></reporting-entity>\
      <severity>major</severity></event></notification>

      JSON:

      data: {"ietf-restconf:notification":{"eventTime":"2013-12-21\
      T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
      tingEntity":{"card":"Ethernet0"},"severity":"major"}}}

   The SSE specification supports the following additional fields:
   "event", "id", and "retry".  A RESTCONF server MAY send the "retry"
   field, and if it does, RESTCONF clients SHOULD use it.  A RESTCONF
   server SHOULD NOT send the "event" or "id" fields, as there are no
   meaningful values that could be used for them that would not be
   redundant to the contents of the notification itself.  RESTCONF
   servers that do not send the "id" field also do not need to support
   the HTTP header field "Last-Event-ID" [W3C.REC-eventsource-20150203].
   RESTCONF servers that do send the "id" field SHOULD support the
   "start-time" query parameter as the preferred means for a client to
   specify where to restart the event stream.

7.  Error Reporting

   HTTP status codes are used to report success or failure for RESTCONF
   operations.  The error information that NETCONF error responses
   contain in the <rpc-error> element is adapted for use in RESTCONF,
   and <errors> data tree information is returned for the "4xx" and
   "5xx" classes of status codes.

   Since an operation resource is defined with a YANG "rpc" statement
   and an action is defined with a YANG "action" statement, a mapping
   from the NETCONF <error-tag> value to the HTTP status code is needed.
   The specific error-tag and response code to use are specific to the
   data model and might be contained in the YANG "description" statement
   for the "action" or "rpc" statement.

              +-------------------------+------------------+
              | error-tag               | status code      |
              +-------------------------+------------------+
              | in-use                  | 409              |
              |                         |                  |
              | invalid-value           | 400, 404, or 406 |
              |                         |                  |
              | (request) too-big       | 413              |
              |                         |                  |
              | (response) too-big      | 400              |
              |                         |                  |
              | missing-attribute       | 400              |
              |                         |                  |
              | bad-attribute           | 400              |
              |                         |                  |
              | unknown-attribute       | 400              |
              |                         |                  |
              | bad-element             | 400              |
              |                         |                  |
              | unknown-element         | 400              |
              |                         |                  |
              | unknown-namespace       | 400              |
              |                         |                  |
              | access-denied           | 401 or 403       |
              |                         |                  |
              | lock-denied             | 409              |
              |                         |                  |
              | resource-denied         | 409              |
              |                         |                  |
              | rollback-failed         | 500              |
              |                         |                  |
              | data-exists             | 409              |
              |                         |                  |
              | data-missing            | 409              |
              |                         |                  |
              | operation-not-supported | 405 or 501       |
              |                         |                  |
              | operation-failed        | 412 or 500       |
              |                         |                  |
              | partial-operation       | 500              |
              |                         |                  |
              | malformed-message       | 400              |
              +-------------------------+------------------+

                  Mapping from <error-tag> to Status Code

7.1.  Error Response Message

   When an error occurs for a request message on any resource type and
   the status code that will be returned is in the "4xx" range (except
   for status code "403 Forbidden"), the server SHOULD send a response
   message-body containing the information described by the
   "yang-errors" YANG data template within the "ietf-restconf" module
   found in Section 8.  The Content-Type of this response message MUST
   be "application/yang-data", plus, optionally, a structured syntax
   name suffix.

   The client SHOULD specify the desired encoding(s) for response
   messages by specifying the appropriate media type(s) in the
   "Accept" header.  If the client did not specify an "Accept" header,
   then the same structured syntax name suffix used in the request
   message SHOULD be used, or the server MAY choose any supported
   message-encoding format.  If there is no request message, the server
   MUST select "application/yang-data+xml" or
   "application/yang-data+json", depending on server preference.  All of
   the examples in this document, except for the one below, assume that
   XML encoding will be returned if there is an error.

   YANG tree diagram for <errors> data:

     +---- errors
           +---- error*
              +---- error-type       enumeration
              +---- error-tag        string
              +---- error-app-tag?   string
              +---- error-path?      instance-identifier
              +---- error-message?   string
              +---- error-info?

   The semantics and syntax for RESTCONF error messages are defined with
   the "yang-errors" YANG data template extension, found in Section 8.

   Examples:

   The following example shows an error returned for a "lock-denied"
   error that can occur if a NETCONF client has locked a datastore.  The
   RESTCONF client is attempting to delete a data resource.  Note that
   an "Accept" header field is used to specify the desired encoding for
   the error message.  There would be no response message-body content
   if this operation was successful.

      DELETE /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com
      Accept: application/yang-data+json

   The server might respond as follows:

      HTTP/1.1 409 Conflict
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+json

      {
        "ietf-restconf:errors" : {
          "error" : [
            {
              "error-type" : "protocol",
              "error-tag" : "lock-denied",
              "error-message" : "Lock failed; lock already held"
            }
          ]
        }
      }

   The following example shows an error returned for a "data-exists"
   error on a data resource.  The "jukebox" resource already exists, so
   it cannot be created.

   The client might send the following:

      POST /restconf/data/example-jukebox:jukebox HTTP/1.1
      Host: example.com

   The server might respond as follows:

      HTTP/1.1 409 Conflict
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+xml

      <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
        <error>
          <error-type>protocol</error-type>
          <error-tag>data-exists</error-tag>
          <error-path
            xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
            xmlns:jbox="https://example.com/ns/example-jukebox">\
            /rc:restconf/rc:data/jbox:jukebox
          </error-path>
          <error-message>
            Data already exists; cannot create new resource
          </error-message>
        </error>
      </errors>

8.  RESTCONF Module

   The "ietf-restconf" module defines conceptual definitions within an
   extension and two groupings, which are not meant to be implemented as
   datastore contents by a server.  For example, the "restconf"
   container is not intended to be implemented as a top-level data node
   (under the "/restconf/data" URI).

   Note that the "ietf-restconf" module does not have any
   protocol-accessible objects, so no YANG tree diagram is shown.

   <CODE BEGINS>

   file "ietf-restconf@2017-01-26.yang"

   module ietf-restconf {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
     prefix "rc";

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        Author:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Author:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Author:   Kent Watsen
                  <mailto:kwatsen@juniper.net>";

     description
       "This module contains conceptual YANG specifications
        for basic RESTCONF media type definitions used in
        RESTCONF protocol messages.

        Note that the YANG definitions within this module do not
        represent configuration data of any kind.
        The 'restconf-media-type' YANG extension statement
        provides a normative syntax for XML and JSON
        message-encoding purposes.

        Copyright (c) 2017 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 8040; see
        the RFC itself for full legal notices.";

     revision 2017-01-26 {
       description
         "Initial revision.";
       reference
         "RFC 8040: RESTCONF Protocol.";
     }

     extension yang-data {
       argument name {
         yin-element true;
       }
       description
         "This extension is used to specify a YANG data template that
          represents conceptual data defined in YANG.  It is
          intended to describe hierarchical data independent of
          protocol context or specific message-encoding format.
          Data definition statements within a yang-data extension
          specify the generic syntax for the specific YANG data
          template, whose name is the argument of the 'yang-data'
          extension statement.

          Note that this extension does not define a media type.
          A specification using this extension MUST specify the
          message-encoding rules, including the content media type.

          The mandatory 'name' parameter value identifies the YANG
          data template that is being defined.  It contains the
          template name.

          This extension is ignored unless it appears as a top-level
          statement.  It MUST contain data definition statements
          that result in exactly one container data node definition.
          An instance of a YANG data template can thus be translated
          into an XML instance document, whose top-level element
          corresponds to the top-level container.

          The module name and namespace values for the YANG module using
          the extension statement are assigned to instance document data
          conforming to the data definition statements within
          this extension.

          The substatements of this extension MUST follow the
          'data-def-stmt' rule in the YANG ABNF.

          The XPath document root is the extension statement itself,
          such that the child nodes of the document root are
          represented by the data-def-stmt substatements within
          this extension.  This conceptual document is the context
          for the following YANG statements:

            - must-stmt
            - when-stmt
            - path-stmt
            - min-elements-stmt
            - max-elements-stmt
            - mandatory-stmt
            - unique-stmt
            - ordered-by
            - instance-identifier data type

          The following data-def-stmt substatements are constrained
          when used within a 'yang-data' extension statement.

            - The list-stmt is not required to have a key-stmt defined.
            - The if-feature-stmt is ignored if present.
            - The config-stmt is ignored if present.
            - The available identity values for any 'identityref'
              leaf or leaf-list nodes are limited to the module
              containing this extension statement and the modules
              imported into that module.
         ";
     }

     rc:yang-data yang-errors {
       uses errors;
     }

     rc:yang-data yang-api {
       uses restconf;
     }

     grouping errors {
       description
         "A grouping that contains a YANG container
          representing the syntax and semantics of a
          YANG Patch error report within a response message.";

       container errors {
         description
           "Represents an error report returned by the server if
            a request results in an error.";

         list error {
           description
             "An entry containing information about one
              specific error that occurred while processing
              a RESTCONF request.";
           reference
             "RFC 6241, Section 4.3.";

           leaf error-type {
             type enumeration {
               enum transport {
                 description
                   "The transport layer.";
               }
               enum rpc {
                 description
                   "The rpc or notification layer.";
               }
               enum protocol {
                 description
                   "The protocol operation layer.";
               }
               enum application {
                 description
                   "The server application layer.";
               }
             }
             mandatory true;
             description
               "The protocol layer where the error occurred.";
           }

           leaf error-tag {
             type string;
             mandatory true;
             description
               "The enumerated error-tag.";
           }

           leaf error-app-tag {
             type string;
             description
               "The application-specific error-tag.";
           }

           leaf error-path {
             type instance-identifier;
             description
               "The YANG instance identifier associated
                with the error node.";
           }

           leaf error-message {
             type string;
             description
               "A message describing the error.";
           }

           anydata error-info {
              description
                "This anydata value MUST represent a container with
                 zero or more data nodes representing additional
                 error information.";
           }
         }
       }
     }

     grouping restconf {
       description
         "Conceptual grouping representing the RESTCONF
          root resource.";

       container restconf {
         description
           "Conceptual container representing the RESTCONF
            root resource.";

         container data {
           description
             "Container representing the datastore resource.
              Represents the conceptual root of all state data
              and configuration data supported by the server.
              The child nodes of this container can be any data
              resources that are defined as top-level data nodes
              from the YANG modules advertised by the server in
              the 'ietf-yang-library' module.";
         }

         container operations {
           description
             "Container for all operation resources.

              Each resource is represented as an empty leaf with the
              name of the RPC operation from the YANG 'rpc' statement.

              For example, the 'system-restart' RPC operation defined
              in the 'ietf-system' module would be represented as
              an empty leaf in the 'ietf-system' namespace.  This is
              a conceptual leaf and will not actually be found in
              the module:

                 module ietf-system {
                   leaf system-reset {
                     type empty;
                   }
                 }

              To invoke the 'system-restart' RPC operation:

                 POST /restconf/operations/ietf-system:system-restart

              To discover the RPC operations supported by the server:

                 GET /restconf/operations

              In XML, the YANG module namespace identifies the module:

                <system-restart
                   xmlns='urn:ietf:params:xml:ns:yang:ietf-system'/>

              In JSON, the YANG module name identifies the module:

                { 'ietf-system:system-restart' : [null] }
             ";
         }

         leaf yang-library-version {
           type string {
             pattern '\d{4}-\d{2}-\d{2}';
           }
           config false;
           mandatory true;
           description
             "Identifies the revision date of the 'ietf-yang-library'
              module that is implemented by this RESTCONF server.
              Indicates the year, month, and day in YYYY-MM-DD
              numeric format.";
         }
       }
     }

   }

   <CODE ENDS>