<?xml version="1.0" encoding="US-ASCII"?> version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?> "rfc2629-xhtml.ent">
<rfc category="std" xmlns:xi="http://www.w3.org/2001/XInclude"
number="8650"
docName="draft-ietf-netconf-restconf-notif-15"
     ipr="trust200902">
updates=""
obsoletes=""
category="std"
consensus="true"
submissionType="IETF"
ipr="trust200902"
tocInclude="true"
symRefs="true"
sortRefs="true"
xml:lang="en"
version="3">
  <front>

    <title abbrev="RESTCONF-Notif">Dynamic subscription abbrev="RESTCONF Transport for Event Notifications">Dynamic Subscription to YANG Events and Datastores over RESTCONF</title>
    <seriesInfo name="RFC" value="8650"/>
    <author fullname="Eric Voit" initials="E." surname="Voit">
      <organization>Cisco Systems</organization>
      <address>
        <email>evoit@cisco.com</email>
      </address>
    </author>
    <author fullname="Reshad Rahman" initials="R" initials="R." surname="Rahman">
      <organization>Cisco Systems</organization>
      <address>
        <email>rrahman@cisco.com</email>
      </address>
    </author>
    <author fullname="Einar Nilsen-Nygaard" initials="E" initials="E." surname="Nilsen-Nygaard">
      <organization>Cisco Systems</organization>
      <address>
        <email>einarnn@cisco.com</email>
      </address>
    </author>
    <author fullname="Alexander Clemm" initials="A" initials="A." surname="Clemm">
        <organization>Huawei</organization>
      <organization>Futurewei</organization>
      <address>
        <email>ludwig@clemm.org</email>
      </address>
    </author>
    <author fullname="Andy Bierman" initials="A" initials="A." surname="Bierman">
      <organization>YumaWorks</organization>
      <address>
        <email>andy@yumaworks.com</email>
      </address>
    </author>
    <date day="11" month="June" month="November" year="2019"/>
    <area>Operations &amp; Management</area>
    <workgroup>NETCONF</workgroup>

    <keyword>Draft</keyword>

    <keyword>YANG-Push</keyword>
    <abstract>
      <t>This document provides a RESTCONF binding to the dynamic subscription
      capability of both subscribed notifications and YANG-Push.</t>
    </abstract>
  </front>
  <middle>
    <section title="Introduction"> numbered="true" toc="default">
      <name>Introduction</name>

      <t>Mechanisms to support event subscription and push YANG-Push are defined in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>. target="RFC8639" format="default"/>. Enhancements to <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> which target="RFC8639" format="default"/> that enable YANG datastore subscription and push YANG-Push are defined in <xref target="I-D.ietf-netconf-yang-push"/>. target="RFC8641" format="default"/>.
This document provides a transport specification for dynamic subscriptions over RESTCONF <xref target="RFC8040"/>. target="RFC8040" format="default"/>.  Requirements for these mechanisms are captured in <xref target="RFC7923"/>.</t> target="RFC7923" format="default"/>.</t>
      <t>The streaming of notifications encapsulating that encapsulate the resulting information push is done via the mechanism described in section 6.3 of <xref target="RFC8040"/>. target="RFC8040" sectionFormat="of" section="6.3" format="default"/>.  </t>
    </section>
    <section title="Terminology">
      <t>The numbered="true" toc="default">
      <name>Terminology</name>
        <t>
    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
    NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
    "<bcp14>MAY</bcp14>", and
   "OPTIONAL" "<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as
    described in BCP
   14 BCP&nbsp;14 <xref target="RFC2119"/> <xref target="RFC8174"/>
    when, and only when, they appear in all capitals, as shown here.</t> here.
        </t>

      <t>The following terms use the definitions from <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>: target="RFC8639" format="default"/>: dynamic subscription, event stream, notification message, publisher, receiver, subscriber, and subscription.</t>
      <t>Other terms reused include datastore, which is defined in <xref target="RFC8342"/>, target="RFC8342" format="default"/>, and HTTP2 stream HTTP/2 stream, which maps to the definition of "stream" within <xref target="RFC7540"/>, Section 2.</t>

      <t>[ note to the RFC Editor - please replace XXXX within this document with the number of this document ]</t> target="RFC7540" sectionFormat="comma" section="2" format="default"/>.</t>
    </section>
    <section anchor="dyn-subs" title="Dynamic Subscriptions"> numbered="true" toc="default">
      <name>Dynamic Subscriptions</name>
      <t>This section provides specifics on how to establish and maintain dynamic subscriptions over RESTCONF <xref target="RFC8040"/>. target="RFC8040" format="default"/>. Subscribing to event streams is accomplished in this way via RPCs defined within <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> Section 2.4. target="RFC8639" sectionFormat="comma" section="2.4" format="default"/>. The RPCs are done via RESTCONF POSTs. YANG datastore subscription is accomplished via augmentations to <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> target="RFC8639" format="default"/> as described within <xref target="I-D.ietf-netconf-yang-push"/> Section 4.4.</t> target="RFC8641" sectionFormat="comma" section="4.4" format="default"/>.</t>

      <t>As described in <xref target="RFC8040"/> Section 6.3, target="RFC8040" sectionFormat="of"
      section="6.3" format="default"/>, a GET needs to be made against performed on a
      specific URI on the publisher. Subscribers cannot pre-determine predetermine the URI
      against which a subscription might exist on a publisher, as the URI will
      only exist after the "establish-subscription" RPC has been
      accepted. Therefore, the POST for the "establish-subscription" RPC
      replaces the GET request for the "location" leaf which that is used in <xref target="RFC8040"/>
      target="RFC8040" format="default"/> to obtain the URI. The subscription
      URI will be determined and sent as part of the response to the
      "establish-subscription" RPC, and a subsequent GET to this URI will be
      done in order to start the flow of notification messages back to the
      subscriber.  A  As specified in <xref target="RFC8639" sectionFormat="of"
      section="2.4.1" format="default"/>, a subscription does not move to the active state as per Section 2.4.1. of <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>
      until the GET is received. </t> received.</t>
      <section title="Transport Connectivity"> numbered="true" toc="default">
        <name>Transport Connectivity</name>
        <t>For a dynamic subscription, where when a RESTCONF session doesn't already exist, a new RESTCONF session is initiated from the subscriber.</t>
        <t>As stated in Section 2.1 of <xref target="RFC8040"/>, target="RFC8040" sectionFormat="of" section="2.1" format="default"/>, a subscriber MUST <bcp14>MUST</bcp14> establish the HTTP session over TLS <xref target="RFC8446"/> target="RFC8446" format="default"/> in order to secure the content in transit.</t>

   <t>Without the involvement of additional protocols, HTTP sessions by
   themselves do not allow for a support quick recognition of when the loss of the
   communication path has been lost with to the publisher. Where quick recognition of the loss of a publisher is required, a subscriber SHOULD <bcp14>SHOULD</bcp14> use a TLS heartbeat <xref target="RFC6520"/>, target="RFC6520" format="default"/>, just from subscriber to publisher, to track HTTP session continuity.</t>

        <t>Loss of the heartbeat MUST <bcp14>MUST</bcp14> result in the teardown
of any subscription related subscription-related TCP sessions between those endpoints being torn down. endpoints.
A subscriber can then attempt to re-establish the dynamic subscription by using the procedure described in <xref target="SSE"/>.</t> target="SSE" format="default"/>.</t>
      </section>
      <section title="Discovery"> numbered="true" toc="default">
        <name>Discovery</name>
        <t>Subscribers can learn what which event streams a RESTCONF server supports by querying the "streams" container of ietf-subscribed-notification.yang ietf-subscribed-notifications.yang in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>. target="RFC8639" format="default"/>. Support for the "streams" container of ietf-restconf-monitoring.yang in <xref target="RFC8040"/> target="RFC8040" format="default"/> is not required. In the case when the RESTCONF binding specified by this document is used to convey the "streams" container from ietf-restconf-monitoring.yang (i.e., that feature is supported), any event streams contained therein are also expected to be present in the "streams" container of ietf-restconf-monitoring.yang.</t>
        <t>Subscribers can learn what which datastores a RESTCONF server supports by following Section 2 of <xref target="I-D.draft-ietf-netconf-nmda-restconf"/>. target="RFC8527" sectionFormat="of" section="2" format="default"/>. </t>
      </section>
      <section title="RESTCONF numbered="true" toc="default">
        <name>RESTCONF RPCs and HTTP Status Codes"> Codes</name>
        <t>Specific HTTP responses response codes as defined in <xref target="RFC7231"/> section 6 target="RFC7231" sectionFormat="of" section="6" format="default"/> will indicate the result of RESTCONF RPC requests with the publisher.  An HTTP status code of 200 is the proper response to any successful RPC defined within <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> target="RFC8639" format="default"/> or <xref target="I-D.ietf-netconf-yang-push"/>.</t> target="RFC8641" format="default"/>.</t>
        <t>If a publisher fails to serve the RPC request for one of the reasons indicated in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> Section 2.4.6 target="RFC8639" sectionFormat="of" section="2.4.6" format="default"/> or <xref target="I-D.ietf-netconf-yang-push"/> Appendix A, target="RFC8641" sectionFormat="of" section="A" format="default"/>, this will be indicated by an appropriate error code, as shown below, transported in the HTTP response.</t>

        <t>When an HTTP error code is returned, the RPC reply MUST <bcp14>MUST</bcp14> include
an "rpc-error" &lt;rpc-error&gt; element per <xref target="RFC8040"/> Section 7.1 target="RFC8040" sectionFormat="of" section="7.1" format="default"/>
with the following parameter values:
        <list style="symbols">
      <t>an
        </t>
        <ul spacing="normal">
          <li>an "error-type" node of "application".</t>
      <t>an "application".</li>
          <li>an "error-tag" node with the whose value being is a string that corresponds
           to an identity associated with the error.  This "error-tag" will
           come from one of two places.  Either it places and will correspond to the error
           identities either within
           <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> section 2.4.6 target="RFC8639" sectionFormat="of" section="2.4.6" format="default"/>
           for general subscription errors:</t>
    </list></t>

    <figure align="left">
       <artwork><![CDATA[
    error identity         uses error-tag           HTTP Code
    ---------------------- --------------           ---------
    dscp-unavailable       invalid-value            400
    encoding-unsupported   invalid-value            400
    filter-unsupported     invalid-value            400
    insufficient-resources resource-denied          409
    no-such-subscription   invalid-value            404
    replay-unsupported     operation-not-supported  501
       ]]></artwork>
    </figure>

    <t><list style="none">
       <t>Or this "error-tag" will correspond to the error identities errors (<xref target="gen-sub-errors" format="default"/>)
           or within <xref target="I-D.ietf-netconf-yang-push"/> Appendix A.1 target="RFC8641" sectionFormat="of" section="A.1" format="default"/>
           for subscription errors specific to YANG datastores:</t>
    </list></t>

    <figure align="left">
       <artwork><![CDATA[
    error identity              uses error-tag          HTTP Code
    ----------------------      --------------          ---------
    cant-exclude                operation-not-supported 501
    datastore-not-subscribable  invalid-value           400
    no-such-subscription-resync invalid-value           404
    on-change-unsupported       operation-not-supported 501
    on-change-sync-unsupported  operation-not-supported 501
    period-unsupported          invalid-value           400
    update-too-big              too-big                 400
    sync-too-big                too-big                 400
    unchanging-selection        operation-failed        500
       ]]></artwork>
    </figure>

    <t><list style="symbols">

          <t>an datastores (<xref
	   target="datastore-specific-errors" format="default"/>).</li>
          <li>an "error-app-tag" node with the whose value being is a string that corresponds to an
          identity associated with the error, as defined in
           <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> section 2.4.6 target="RFC8639" sectionFormat="of" section="2.4.6" format="default"/>
           for general subscriptions, and subscriptions or
           <xref target="I-D.ietf-netconf-yang-push"/> Appendix A.1, target="RFC8641" sectionFormat="of" section="A.1" format="default"/>
           for datastore subscriptions. subscription errors specific to YANG datastores. The tag to use depends on the RPC for which the
           error occurred.  Viable errors for different RPCs are as follows:</t>

        </list></t>

        <figure align="left">
            <artwork><![CDATA[
         RPC                     select found in <xref target="rpc-errors" format="default"/>.</li>
        </ul>

<table anchor="gen-sub-errors">
	<name>General Subscription Error Identities and Associated "error-tag" Use</name>
	<thead>
	<tr>
		<th>Error identity</th>
		<th>Uses "error-tag"</th>
		<th>HTTP code</th>
	</tr>
	</thead>
	<tbody>
	<tr>
		<td>dscp-unavailable</td>
		<td>invalid-value</td>
		<td>400</td>
	</tr>
	<tr>
		<td>encoding-unsupported</td>
		<td>invalid-value</td>
		<td>400</td>
	</tr>
	<tr>
		<td>filter-unsupported</td>
		<td>invalid-value</td>
		<td>400</td>
	</tr>
	<tr>
		<td>insufficient-resources</td>
		<td>resource-denied</td>
		<td>409</td>
	</tr>
	<tr>
		<td>no-such-subscription</td>
		<td>invalid-value</td>
		<td>404</td>
	</tr>
	<tr>
		<td>replay-unsupported</td>
		<td>operation-not-supported</td>
		<td>501</td>
	</tr>
	</tbody>
</table>
<table anchor="datastore-specific-errors">
	<name>Datastore-Specific Error Identities and Associated "error-tag" Use</name>
	<thead>
	<tr>
		<th>Error identity</th>
		<th>Uses "error-tag"</th>
		<th>HTTP code</th>
	</tr>
	</thead>
	<tbody>
	<tr>
		<td>cant-include</td>
		<td>operation-not-supported</td>
		<td>501</td>
	</tr>
	<tr>
		<td>datastore-not-subscribable</td>
		<td>invalid-value</td>
		<td>400</td>
	</tr>
	<tr>
		<td>no-such-subscription-resync</td>
		<td>invalid-value</td>
		<td>404</td>
	</tr>
	<tr>
		<td>on-change-unsupported</td>
		<td>operation-not-supported</td>
		<td>501</td>
	</tr>
	<tr>
		<td>on-change-sync-unsupported</td>
		<td>operation-not-supported</td>
		<td>501</td>
	</tr>
	<tr>
		<td>period-unsupported</td>
		<td>invalid-value</td>
		<td>400</td>
	</tr>
	<tr>
		<td>update-too-big</td>
		<td>too-big</td>
		<td>400</td>
	</tr>
	<tr>
		<td>sync-too-big</td>
		<td>too-big</td>
		<td>400</td>
	</tr>
	<tr>
		<td>unchanging-selection</td>
		<td>operation-failed</td>
		<td>500</td>
	</tr>
	</tbody>
</table>
<table anchor="rpc-errors">
	<name>RPC Errors and Associated Error Identities</name>
	<thead>
	<tr>
		<th>RPC</th>
		<th>Select an identity with a base
         ----------------------  ------------------------------
         establish-subscription  establish-subscription-error
         modify-subscription     modify-subscription-error
         delete-subscription     delete-subscription-error
         kill-subscription       delete-subscription-error
         resync-subscription     resync-subscription-error
              ]]></artwork>
        </figure> base</th>
	</tr>
	</thead>
	<tbody>
	<tr>
         <td>establish-subscription</td>
         <td>establish-subscription-error</td>
	</tr>
	<tr>
         <td>modify-subscription</td>
         <td>modify-subscription-error</td>
	</tr>
	<tr>
         <td>delete-subscription</td>
         <td>delete-subscription-error</td>
	</tr>
	<tr>
         <td>kill-subscription</td>
         <td>delete-subscription-error</td>
	</tr>
	<tr>
         <td>resync-subscription</td>
         <td>resync-subscription-error</td>
	</tr>
	</tbody>
</table>
        <t>Each error identity will be inserted as the "error-app-tag" using JSON encoding following the form &lt;modulename&gt;:&lt;identityname&gt;.  An example of such a valid encoding would be "ietf-subscribed-notifications:no-such-subscription".</t>
        <t>In the case of error responses to an "establish-subscription" or
	"modify-subscription" request request, there is the option of including to include an
	"error-info" node.  This node may contain hints for parameter settings
	that might lead to successful RPC requests in the future.   Following are Tables <xref target="error-info-estab-sub" format="counter"/> and <xref target="error-info-mod-sub" format="counter"/> show the yang-data structures which that may be returned:</t>

        <figure align="left">
          <artwork><![CDATA[
      establish-subscription returns returned.</t>

<table anchor="error-info-estab-sub">
	<name>Optional "error-info" Node Hints for an "establish-subscription" Request</name>
	<thead>
	<tr>
		<th>Target:</th>
		<th>Return hints in yang-data structure
      ---------------------- ------------------------------------
      target: event stream   establish-subscription-stream-error-info
      target: datastore      establish-subscription-datastore-error-info

      modify-subscription    returns structure</th>
	</tr>
        </thead>
	<tbody>
	<tr>
                 <td>event stream</td>
                 <td>establish-subscription-stream-error-info</td>
	</tr>
	<tr>
                 <td>datastore</td>
                 <td>establish-subscription-datastore-error-info</td>
	</tr>
	</tbody>
</table>
<table anchor="error-info-mod-sub">
        <name>Optional "error-info" Node Hints for an "modify-subscription" Request</name>
        <thead>
        <tr>
                 <th>Target:</th>
                 <th>Returns hints in yang-data structure
      ---------------------- ------------------------------------
      target: event stream   modify-subscription-stream-error-info
      target: datastore      modify-subscription-datastore-error-info

      The structure</th>
        </tr>
        </thead>
        <tbody>
        <tr>
                 <td>event stream</td>
                 <td>modify-subscription-stream-error-info</td>
        </tr>
        <tr>
                 <td>datastore</td>
                 <td>modify-subscription-datastore-error-info</td>
        </tr>
        </tbody>
</table>
      <t>The yang-data included within "error-info" SHOULD NOT <bcp14>SHOULD NOT</bcp14> include the
      optional leaf "reason", as such a leaf would be redundant
      with information that is already placed within the
      "error-app-tag".

      In
</t>

      <t>In case of an rpc error &lt;rpc-error&gt; as a result of a "delete-subscription", a
      "kill-subscription", or a "resync-subscription" request, no
      "error-info" needs to be included, as the "subscription-id" is
      the only RPC input parameter parameter, and no hints regarding this RPC input
      parameters need to be provided.
            ]]></artwork>
        </figure>
</t>
        <t>Note that "error-path" <xref target="RFC8040"/> target="RFC8040" format="default"/> does not need to be included with the "rpc-error" &lt;rpc-error&gt; element, as subscription errors are generally associated with the choice of RPC input parameters. </t>
      </section>
      <section anchor="SSE" title="Call numbered="true" toc="default">
        <name>Call Flow for Server-Sent Events"> Events</name>
        <t>The call flow for Server-Sent Events (SSE) is defined in <xref target="dyn-sse"/>.
	target="dyn-sse" format="default"/>.  The logical connections denoted
	by (a) and (b) can be a TCP connection or an HTTP2 HTTP/2 stream (if HTTP2 HTTP/2
	is used, multiple HTTP2 HTTP/2 streams can be carried in one TCP
	connection). Requests to RPCs as defined in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> target="RFC8639"
	format="default"/> or <xref target="I-D.ietf-netconf-yang-push"/> augmented RPCs target="RFC8641" format="default"/> are
	sent on a connection indicated by (a).  A successful
	"establish-subscription" will result in an RPC response returned with
	both a subscription identifier which that uniquely identifies a
	subscription, as well as a URI which that uniquely identifies the location
	of subscription on the publisher (b). This URI is defined via the
	"uri" leaf in the Data Model data model in <xref target="YANG-module"/>. target="YANG-module"
	format="default"/>. </t>
        <t>An HTTP GET is then sent on a separate logical connection (b) to the URI on the publisher.  This signals the publisher to initiate the flow of notification messages which that are sent in SSE <xref target="W3C-20150203"/> target="W3C-20150203" format="default"/> as a response to the GET. There cannot be two or more simultaneous GET requests on a subscription URI: any GET request received while there is a current GET request on the same URI MUST <bcp14>MUST</bcp14> be rejected with HTTP error code 409.</t>
        <t>As described in <xref target="RFC8040"/> Section 6.4, target="RFC8040" sectionFormat="of" section="6.4" format="default"/>, RESTCONF servers SHOULD NOT <bcp14>SHOULD NOT</bcp14> send the "event" or "id" fields in the SSE event notifications.</t>
        <figure title="Dynamic anchor="dyn-sse">
          <name>Dynamic Subscriptions with server-sent events"
                anchor="dyn-sse"
                align="center"> Server-Sent Events</name>
          <artwork height="29" xml:space="preserve"><![CDATA[ name="" type="" align="left" alt=""><![CDATA[
+--------------+                             +--------------+
|  Subscriber  |                             |   Publisher  |
|              |                             |              |
|    Logical   |                             |     Logical  |
|  Connection  |                             |   Connection |
|  (a)  (b)    |                             |    (a)  (b)  |
+--------------+                             +--------------+
    | RESTCONF POST (RPC:establish-subscription)   |
    |--------------------------------------------->|
    |                          HTTP 200 OK (ID,URI)|
    |<---------------------------------------------|
    |    |HTTP GET (URI)                                |
    |    |--------------------------------------------->|
    |    |                                   HTTP 200 OK|
    |    |<---------------------------------------------|
    |    |                           SSE (notif-message)|
    |    |<---------------------------------------------|
    | RESTCONF POST (RPC:modify-subscription)      |    |
    |--------------------------------------------->|    |
    |    |                              HTTP 200 OK|    |
    |<---------------------------------------------|    |
    |    |                   SSE (subscription-modified)|
    |    |<------------------------------------------(c)|
    |    |                           SSE (notif-message)|
    |    |<---------------------------------------------|
    | RESTCONF POST (RPC:delete-subscription)      |    |
    |--------------------------------------------->|    |
    |    |                              HTTP 200 OK|    |
    |<---------------------------------------------|    |
    |    |                                         |    |
    |    |                                         |    |
    (a) (b)                                       (a)  (b) ]]></artwork>
        </figure>
        <t>Additional requirements for dynamic subscriptions over SSE include:</t>
        <t><list style="symbols">
          <t>All
        <ul spacing="normal">

          <li>
   A publisher <bcp14>MUST</bcp14> return all subscription state notifications from a publisher MUST be returned
   in a separate SSE message used by the subscription to
   which the state change refers.</t>
          <t>Subscription refers.
          </li>

          <li>Subscription RPCs MUST NOT <bcp14>MUST NOT</bcp14> use the connection currently providing notification messages for that subscription.</t>
          <t>In subscription.</li>
          <li>In addition to an RPC response for a "modify-subscription" RPC traveling over (a), a "subscription-modified" state change notification MUST <bcp14>MUST</bcp14> be sent within (b).  This allows the receiver to know exactly when, within the stream of events, the new terms of the subscription have been applied to the notification messages.  See arrow (c).</t>
          <t>In (c).</li>
          <li>In addition to any required access permissions (e.g., NACM), Network Configuration Access Control Model (NACM)), the RPCs modify-subscription, resync-subscription "modify-subscription", "resync-subscription", and
delete-subscription SHOULD
"delete-subscription" <bcp14>SHOULD</bcp14> only be allowed by the same RESTCONF username <xref target="RFC8040"/> which target="RFC8040" format="default"/> that invoked establish-subscription. "establish-subscription". Such a restriction generally serves to preserve users' privacy, but exceptions might be made for administrators that may need to modify or delete other users' subscriptions.</t>
          <t>The kill-subscription subscriptions.</li>
          <li>The "kill-subscription" RPC can be invoked by any RESTCONF username with the required administrative permissions.</t>
        </list></t> permissions.</li>
        </ul>
        <t>A publisher MUST <bcp14>MUST</bcp14> terminate a subscription in the following cases:</t>
        <t><list style="symbols">
          <t>Receipt
        <ul spacing="normal">
          <li>Receipt of a "delete-subscription" or a "kill-subscription" RPC for that subscription.</t>
          <t>Loss subscription</li>
          <li>Loss of TLS heartbeat</t>
        </list></t> heartbeat</li>
        </ul>
        <t>A publisher MAY <bcp14>MAY</bcp14> terminate a subscription at any time as stated in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> Section 1.3 </t> target="RFC8639" sectionFormat="of" section="1.3" format="default"/>.</t>
      </section>
    </section>
    <section title="QoS Treatment"> numbered="true" toc="default">
      <name>QoS Treatment</name>
      <t>Qos treatment for event streams is described in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> Section 2.3. target="RFC8639" sectionFormat="of" section="2.3" format="default"/>. In addition, if HTTP2 HTTP/2 is used, the publisher MUST:</t>

      <t><list style="symbols">
        <t>take <bcp14>MUST</bcp14>:</t>
      <ul spacing="normal">
        <li>Take the "weighting" leaf node in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>, target="RFC8639"
	format="default"/> and copy it into the HTTP2 HTTP/2 stream weight, <xref target="RFC7540"/> section 5.3, target="RFC7540" sectionFormat="of" section="5.3" format="default"/>, and </t>

        <t>take </li>
        <li>Take any existing subscription "dependency", as specified by the
	"dependency" leaf node in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>, target="RFC8639" format="default"/>,
	and use the HTTP2 HTTP/2 stream for the parent subscription as the HTTP2 HTTP/2
	stream dependency, dependency (as described in <xref target="RFC7540"/> section 5.3.1, target="RFC7540" sectionFormat="of"
	section="5.3.1" format="default"/>) of the dependent subscription.</t>
        <t>set
	subscription.</li>
        <li>Set the exclusive flag, <xref target="RFC7540"/> section 5.3.1, flag (<xref target="RFC7540" sectionFormat="of" section="5.3.1" format="default"/>) to 0.</t>
      </list></t> 0.</li>
      </ul>
      <t>For dynamic subscriptions with the same DSCP Differentiated Services Code Point (DSCP) value to a specific publisher, it is recommended that the subscriber sends all URI GET requests on a common HTTP2 HTTP/2 session (if HTTP2 HTTP/2 is used). Conversely, a subscriber can not cannot use a common HTTP2 HTTP/2 session for subscriptions with different DSCP values.</t>
    </section>
    <section title="Notification Messages"> numbered="true" toc="default">
      <name>Notification Messages</name>
      <t>Notification messages transported over RESTCONF will be encoded according to <xref target="RFC8040"/>, section 6.4.</t> target="RFC8040" sectionFormat="comma" section="6.4" format="default"/>.</t>
    </section>
    <section title="YANG Tree" anchor="YANG-tree" > numbered="true" toc="default">
      <name>YANG Tree</name>

      <t> The YANG model module defined in <xref target="YANG-module"/> target="YANG-module"
      format="default"/> has one leaf augmented into that augments three places nodes of <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>.</t>
      <figure>
            <artwork><![CDATA[ target="RFC8639" format="default"/>.</t>

      <sourcecode name="" type="yangtree"><![CDATA[
module: ietf-restconf-subscribed-notifications
  augment /sn:establish-subscription/sn:output:
    +--ro uri?   inet:uri
  augment /sn:subscriptions/sn:subscription:
    +--ro uri?   inet:uri
  augment /sn:subscription-modified:
    +--ro uri?   inet:uri
            ]]></artwork>
      </figure> ]]></sourcecode>
    </section>
    <section title="YANG module" anchor="YANG-module" > numbered="true" toc="default">
      <name>YANG Module</name>
      <t>This module references <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>.</t>

      <figure>
         <artwork name="ietf-restconf-subscribed-notifications@2019-01-11.yang"><![CDATA[
<CODE BEGINS> file
   "ietf-restconf-subscribed-notifications@2019-01-11.yang" target="RFC8639" format="default"/>.</t>

      <sourcecode name="ietf-restconf-subscribed-notifications@2019-10-15.yang" type="yang" markers="true"><![CDATA[
module ietf-restconf-subscribed-notifications {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:"
          + "ietf-restconf-subscribed-notifications";
  prefix rsn;

  import ietf-subscribed-notifications {
    prefix sn;
  }
  import ietf-inet-types {
    prefix inet;
  }

  organization
    "IETF NETCONF (Network Configuration) Working Group";
  contact
    "WG Web:   <http:/tools.ietf.org/wg/netconf/>   <https://datatracker.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>

     Editor:   Eric Voit
               <mailto:evoit@cisco.com>

     Editor:   Alexander Clemm
               <mailto:ludwig@clemm.org>

     Editor:   Reshad Rahman
               <mailto:rrahman@cisco.com>";
  description
    "Defines RESTCONF as a supported transport for subscribed
     event notifications.

     Copyright (c) 2019 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
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX; 8650; see the
     RFC itself for full legal notices.";

  revision 2019-01-11 2019-10-15 {
    description
      "Initial version";
    reference
      "RFC XXXX: RESTCONF Transport for Event Notifications"; 8650: Dynamic Subscription to YANG Events and Datastores
       over RESTCONF";
  }

  grouping uri {
    description
      "Provides a reusable description of a URI.";
    leaf uri {
      type inet:uri;
      config false;
      description
        "Location of a subscription specific subscription-specific URI on the publisher.";
    }
  }

  augment "/sn:establish-subscription/sn:output" {
    description
      "This augmentation allows RESTCONF specific RESTCONF-specific parameters for a
       response to a publisher's subscription request.";
    uses uri;
  }

  augment "/sn:subscriptions/sn:subscription" {
    description
      "This augmentation allows RESTCONF specific RESTCONF-specific parameters to be
       exposed for a subscription.";
    uses uri;
  }

  augment "/sn:subscription-modified" {
    description
      "This augmentation allows RESTCONF specific RESTCONF-specific parameters to be
       included as part of the notification that a subscription has
       been modified.";
    uses uri;
  }
}
<CODE ENDS>
              ]]></artwork>
          </figure>
]]></sourcecode>
    </section>

    <section title="IANA Considerations"> numbered="true" toc="default">
      <name>IANA Considerations</name>
      <t>
      This document registers the following namespace URI in the "ns"
      subregistry of the "IETF XML Registry" <xref target="RFC3688"/>: target="RFC3688" format="default"/>:
      </t>

      <t>
      URI:
      urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications
      <vspace/>
      Registrant Contact: The IESG.
      <vspace/>
      XML: N/A;

      <dl>
        <dt>URI:</dt>
        <dd>urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications</dd>
        <dt>Registrant Contact:</dt>
        <dd>The IESG.</dd>
        <dt>XML:</dt>
        <dd>N/A; the requested URI is an XML namespace.
      </t> namespace.</dd>
      </dl>
      <t>
      This document registers the following YANG module in the "YANG Module
      Names" registry <xref target="RFC6020"/>:
      </t>

      <t>
      Name:         ietf-restconf-subscribed-notifications
      <vspace/>
      Namespace:
      urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications
      <vspace/>
      Prefix:       rsn
      <vspace/>
      Reference: RFC XXXX: RESTCONF Transport for Event Notifications target="RFC6020" format="default"/>:
      </t>

      <dl>
        <dt>Name:</dt>
        <dd>ietf-restconf-subscribed-notifications</dd>
        <dt>Namespace:</dt>
        <dd>urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications</dd>
        <dt>Prefix:</dt>
        <dd>rsn</dd>
        <dt>Reference:</dt>
        <dd>RFC 8650</dd>
      </dl>
    </section>
    <section anchor="security" title="Security Considerations"> numbered="true" toc="default">
      <name>Security Considerations</name>
      <t>The YANG module specified in this document defines a schema for data that is designed to be accessed via network management transports such as NETCONF <xref target="RFC6241"/> target="RFC6241" format="default"/> or RESTCONF <xref target="RFC8040"/>. target="RFC8040" format="default"/>.  The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) <xref target="RFC6242"/>. target="RFC6242" format="default"/>.  The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS <xref target="RFC8446"/>.</t> target="RFC8446" format="default"/>.</t>
      <t>The Network Configuration Access Control Model (NACM) <xref target="RFC8341" format="default"/>
    provides the means to restrict access for particular NETCONF or
    RESTCONF users to a preconfigured subset of all available NETCONF
    or RESTCONF protocol operations and content.</t>
      <t>The one new data node introduced in this YANG module may be considered sensitive or vulnerable in some network environments.  It is thus important to control read access (e.g., via get, get-config, or notification) to this data nodes. node.  These are the subtrees and data nodes and their sensitivity/vulnerability:</t>
      <t>Container: "/subscriptions"</t>
      <t><list style="symbols">
        <t>"uri":
      <ul spacing="normal">
        <li>"uri": leaf will show where subscribed resources might be located on a publisher.  Access control must be set so that only someone with proper access permissions, i.e., the same RESTCONF <xref target="RFC8040"/> target="RFC8040" format="default"/> user credentials which that invoked the corresponding "establish-subscription", has the ability to access this resource.</t>
      </list></t> resource.</li>
      </ul>
      <t>The subscription URI is implementation specific and is encrypted via the use of TLS. Therefore, even if an attacker succeeds in guessing the subscription URI, a RESTCONF username <xref target="RFC8040"/> target="RFC8040" format="default"/> with the required administrative permissions must be used to be able to access or modify that subscription. It is recommended that the subscription URI values not be easily predictable.</t>
      <t>The access permission considerations for the RPCs modify-subscription, resync-subscription, delete-subscription "modify-subscription", "resync-subscription", "delete-subscription", and kill-subscription "kill-subscription" are described in <xref target="SSE"/>.</t> target="SSE" format="default"/>.</t>
      <t>If a buggy or compromised RESTCONF subscriber sends a number of "establish-subscription" requests, then these subscriptions accumulate and may
    use up system resources.  In such a situation, the publisher MAY <bcp14>MAY</bcp14> also suspend or terminate a subset of the active
    subscriptions from that RESTCONF subscriber in order to reclaim resources and preserve normal operation for the other subscriptions.
</t>
    </section>

    <section title="Acknowledgments">
      <t>We wish to acknowledge the helpful contributions, comments, and suggestions that were received from: Ambika Prasad Tripathy, Alberto Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu and Robert Wilton.</t>
    </section>
  </middle>
  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>
      <?rfc include="reference.RFC.3688"?>
      <?rfc include="reference.RFC.6020"?>
      <?rfc include="reference.RFC.6241"?>
      <?rfc include="reference.RFC.6242"?>
      <?rfc include="reference.RFC.6520"?>
      <?rfc include="reference.RFC.7540"?>
      <?rfc include="reference.RFC.8040"?>
      <?rfc include="reference.RFC.8174"?>
      <?rfc include="reference.RFC.8342"?>
      <?rfc include="reference.RFC.8446"?>

      <reference anchor="I-D.draft-ietf-netconf-subscribed-notifications">
        <front>
          <title>Custom Subscription to Event Streams</title>
          <author fullname="Eric Voit" initials="E" surname="Voit">
            <organization/>
          </author>
          <author fullname="Alexander Clemm" initials="A" surname="Clemm">
            <organization/>
          </author>
          <author fullname="Alberto Gonzalez Prieto" initials="A"
                  surname="Gonzalez Prieto">
            <organization/>
          </author>
          <author fullname="Ambika Prasad Tripathy" initials="A"
                  surname="Tripathy">
            <organization/>
          </author>
          <author fullname="Einar Nilsen-Nygaard" initials="E"
                  surname="Nilsen-Nygaard">
            <organization/>
          </author>
          <date month="January" year="2019"/>
        </front>
        <seriesInfo name="Internet-Draft" value="draft-ietf-netconf-subscribed-notifications-21"/>
        <format target="https://datatracker.ietf.org/doc/draft-ietf-netconf-subscribed-notifications/"
                type="TXT"/>
      </reference>

      <reference anchor="I-D.ietf-netconf-yang-push"
                 target="https://datatracker.ietf.org/doc/draft-ietf-netconf-yang-push/">
        <front>
          <title>Subscribing to YANG datastore push updates</title>

          <author fullname="Alexander Clemm" initials="A" surname="Clemm">
            <organization>Huawei</organization>
          </author>

          <author fullname="Eric Voit" initials="E" surname="Voit">
            <organization>Cisco</organization>
          </author>

          <author fullname="Alberto Gonzalez Prieto" initials="A"
                  surname="Gonzalez Prieto">
            <organization>VMWare</organization>
          </author>

          <author fullname="Ambika Prasad Tripathy" initials="A"
                  surname="Prasad Tripathy">
            <organization>Cisco</organization>
          </author>

          <author fullname="Einar Nilsen-Nygaard" initials="E"
                  surname="Nilsen-Nygaard">
            <organization>Cisco</organization>
          </author>

          <author fullname="Andy Bierman" initials="A"
                  surname="Bierman">
            <organization>YumaWorks</organization>
          </author>

          <author fullname="B Lengyel" initials="B"
                  surname="Lengyel">
            <organization>Ericsson</organization>
          </author>

          <date day="22" month="October" year="2018"/>
        </front>
        <seriesInfo name="Internet-Draft" value="draft-ietf-netconf-yang-push-20"/>
        <format target="https://datatracker.ietf.org/doc/draft-ietf-netconf-yang-push/"
                type="TXT"/>
      </reference>
    <references>
      <name>References</name>
      <references>
        <name>Normative References</name>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3688.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6020.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6241.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6242.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6520.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7540.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8040.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8341.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8342.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8639.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8641.xml"/>
     <reference anchor="W3C-20150203" target="https://www.w3.org/TR/2015/REC-eventsource-20150203/">
          <front>
            <title>Server-Sent Events, World Wide Web Consortium CR
          CR-eventsource-20121211</title> Events</title>
            <author fullname="I Hickson"> Hickson" initials="I" surname="Hickson">
              <organization/>
            </author>
            <date day="03" month="February" year="2015"/>
          </front>
          <seriesInfo name="W3C" value="Recommendation"/>
<annotation>Latest version available at &lt;<eref target="https://www.w3.org/TR/eventsource/" />&gt;.</annotation>
        </reference>
      </references>

    <references title="Informative References">

      <?rfc include="reference.RFC.7231"?>
      <?rfc include="reference.RFC.7923"?>
      <?rfc include="reference.RFC.7951"?>
      <?rfc include="reference.RFC.8347"?>
      <reference anchor="I-D.draft-ietf-netconf-nmda-restconf"
                 target="https://datatracker.ietf.org/doc/draft-ietf-netconf-nmda-restconf/">
        <front>
          <title>RESTCONF Extensions to Support the Network Management Datastore Architecture</title>

          <author fullname="Martin Bjorklund" initials="M" surname="Bjorklund"></author>
          <author fullname="Juergen Schoenwaelder" initials="J" surname="Schoenwaelder"></author>
          <author fullname="Phil Shafer" initials="P" surname="Shafer"></author>
          <author fullname="Kent Watsen" initials="K" surname="Watsen"></author>
          <author fullname="Rob Wilton" initials="R" surname="Wilton"></author>

          <date month="April" year="2018"/>
        </front>
      </reference>

      <reference anchor="I-D.draft-ietf-netconf-netconf-event-notifications"
                 target="https://datatracker.ietf.org/doc/draft-ietf-netconf-netconf-event-notifications/">
        <front>
          <title>NETCONF support for event notifications</title>
          <author fullname="A Clemm" initials="Alexander" surname="Clemm"></author>
          <author fullname="E Voit" initials="Eric" surname="Voit"></author>
          <author fullname="A Gonzalez Prieto" initials="Alberto" surname="Gonzalez Prieto"></author>
          <author fullname="Einar Nilsen-Nygaard" initials="E" surname="Nilsen-Nygaard"></author>
          <author fullname="Ambika Prasad Tripathy" initials="A" surname="Tripathy"></author>
          <date month="May" year="2018"/>
        </front>
      </reference>
      <references>
        <name>Informative References</name>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7231.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7923.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7951.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8347.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8527.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8640.xml"/>
        <reference anchor="XPATH" target="http://www.w3.org/TR/1999/REC-xpath-19991116">
          <front>
            <title>XML Path Language (XPath) Version 1.0</title>
            <author fullname="J Clark" initials="J" surname="Clark"></author> surname="Clark"/>
            <author fullname="S DeRose" initials="S" surname="DeRose"></author> surname="DeRose"/>
            <date day="16" month="November" year="1999"/>
          </front>
          <seriesInfo name="W3C" value="Recommendation"/>
<annotation>Latest version available at &lt;<eref target="https://www.w3.org/TR/xpath/" />&gt;.</annotation>
        </reference>
      </references>
    </references>
    <section title="Examples"> numbered="true" toc="default">
      <name>Examples</name>
      <t>This section is non-normative.  To allow easy comparison, this section mirrors the functional examples shown with NETCONF over XML within <xref target="I-D.draft-ietf-netconf-netconf-event-notifications"/>. target="RFC8640" format="default"/>.  In addition, HTTP2 HTTP/2 vs HTTP1.1 HTTP/1.1 headers are not shown as the contents of the JSON encoded objects are identical within.</t>
      <t>The subscription URI values used in the examples in this section are purely illustrative, and are not indicative of the expected usage which that is described in <xref target="security"/>.</t> target="security" format="default"/>.</t>
      <t>The DSCP values are only for example purposes and are all indicated in decimal since the encoding is JSON <xref target="RFC7951"/>.</t> target="RFC7951" format="default"/>.</t>
      <section title="Dynamic Subscriptions"> numbered="true" toc="default">
        <name>Dynamic Subscriptions</name>
        <section title="Establishing numbered="true" toc="default">
          <name>Establishing Dynamic Subscriptions"> Subscriptions</name>
          <t>The following figure shows two successful
	  "establish-subscription" RPC requests as per <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>. target="RFC8639"
	  format="default"/>.  The first request is given a subscription
	  identifier of 22, and the second, an identifier of 23.</t>
          <figure anchor = "mess-flow-establishment"
          title="Multiple subscriptions anchor="mess-flow-establishment">
            <name>Multiple Subscriptions over RESTCONF/HTTP">
            <artwork><![CDATA[ RESTCONF/HTTP</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
   +------------+                  +-----------+
   | Subscriber |                  | Publisher |
   +------------+                  +-----------+
         |                               |
         |establish-subscription         |
         |------------------------------>|  (a)
         |     HTTP 200 OK, id#22, URI#1 |
         |<------------------------------|  (b)
         |GET (URI#1)                    |
         |------------------------------>|  (c)
         | HTTP 200 OK,notif-mesg (id#22)|
         |<------------------------------|
         |                               |
         |                               |
         |establish-subscription         |
         |------------------------------>|
         |      HTTP 200 OK, id#23, URI#2|
         |<------------------------------|
         |GET (URI#2)                    |
         |------------------------------>|
         |                               |
         |                               |
         |             notif-mesg (id#22)|
         |<------------------------------|
         | HTTP 200 OK,notif-mesg (id#23)|
         |<------------------------------|
         |                               | ]]></artwork>
          </figure>
          <t>To provide examples of the information being transported, example messages for interactions in  <xref target="mess-flow-establishment"/> target="mess-flow-establishment" format="default"/> are detailed below:</t>
          <figure align="center" anchor="establish-subs" title="establish-subscription request (a)"> anchor="establish-subs">
            <name>"establish-subscription" Request (a)</name>
            <artwork name="ex-establish-subscription.json"><![CDATA[ name="ex-establish-subscription.json" type=""
		     align="left" alt=""><![CDATA[
POST /restconf/operations
     /ietf-subscribed-notifications:establish-subscription

{
   "ietf-subscribed-notifications:input": {
      "stream-xpath-filter": "/example-module:foo/",
      "stream": "NETCONF",
      "dscp": 10
   }
} ]]></artwork>
          </figure>
          <t>As the publisher was able to fully satisfy the request, the publisher sends the subscription identifier of the accepted subscription, subscription and the URI:</t>
          <figure align="center" anchor="positive-establish-subs" title="establish-subscription success (b)">
            <artwork><![CDATA[ anchor="positive-establish-subs">
            <name>"establish-subscription" Success (b)</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
HTTP status code - 200

{
   "id": 22,
   "uri": "https://example.com/restconf/subscriptions/22"
} ]]></artwork>
          </figure>
          <t>Upon receipt of the successful response, the subscriber does a
	  GET to the provided URI to start the flow of notification messages.
	  When the publisher receives this, the subscription is moved to the
	  active state (c).</t>
          <figure align="center" anchor="positive-establish-post" title="establish-subscription subsequent POST">
            <artwork><![CDATA[ anchor="positive-establish-post">
            <name>"establish-subscription" Subsequent POST</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
GET /restconf/subscriptions/22 ]]></artwork>
          </figure>
          <t>While not shown in <xref target="mess-flow-establishment"/>, target="mess-flow-establishment" format="default"/>, if the publisher had not been able to fully satisfy the request, or the subscriber has no authorization to establish the subscription, the publisher would have sent an RPC error response. For instance, if the "dscp" value of 10 asserted by the subscriber in <xref target="establish-subs"/> target="establish-subs" format="default"/> proved unacceptable, the publisher may have returned:</t>

          <figure align="center" anchor="negative-establish-subs" title="an unsuccessful establish subscription">
            <artwork><![CDATA[ anchor="negative-establish-subs">
            <name>An Unsuccessful "establish-subscription"</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
HTTP status code - 400

{ "ietf-restconf:errors" : {
    "error" : [
      {
        "error-type": "application",
        "error-tag": "invalid-value",
        "error-severity": "error",
        "error-app-tag":
            "ietf-subscribed-notifications:dscp-unavailable"
      }
    ]
  }
} ]]></artwork>
          </figure>
          <t>The subscriber can use this information in future attempts to establish a subscription.</t>
        </section>
        <section title="Modifying numbered="true" toc="default">
          <name>Modifying Dynamic Subscriptions"> Subscriptions</name>
          <t>An existing subscription may be modified.  The following exchange shows a negotiation of such a modification via several exchanges between a subscriber and a publisher.  This negotiation consists of a failed RPC modification request/response, request/response followed by a successful one.</t>
          <figure anchor = "mess-flow-subs-modification"
                title="Interaction model anchor="mess-flow-subs-modification">
            <name>Interaction Model for successful subscription modification">
            <artwork><![CDATA[ Successful Subscription Modification</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
   +------------+                 +-----------+
   | Subscriber |                 | Publisher |
   +------------+                 +-----------+
         |                              |
         |  notification message (id#23)|
         |<-----------------------------|
         |                              |
         |modify-subscription (id#23)   |
         |----------------------------->|  (d)
         |    HTTP 400 error (with hint)|
         |<-----------------------------|  (e)
         |                              |
         |modify-subscription (id#23)   |
         |----------------------------->|
         |                  HTTP 200 OK |
         |<-----------------------------|
         |                              |
         |            notif-mesg (id#23)|
         |<-----------------------------|
         |                              | ]]></artwork>
          </figure>
          <t>If the subscription being modified in <xref target="mess-flow-subs-modification"/> target="mess-flow-subs-modification" format="default"/> is a datastore subscription as per <xref target="I-D.ietf-netconf-yang-push"/>, target="RFC8641" format="default"/>, the modification request made in (d) may look like that shown in <xref target="simple-modify-subs"/>. target="simple-modify-subs" format="default"/>.  As can be seen, the modifications being attempted are the application of a new xpath XML Path Language (XPath) filter as well as the setting of a new periodic time interval.</t>
          <figure align="center" anchor="simple-modify-subs" title="Subscription modification request (c)"> anchor="simple-modify-subs">
            <name>Subscription Modification Request (c)</name>
            <artwork name="ex-modify-subscription.json"><![CDATA[ name="ex-modify-subscription.json" type="" align="left" alt=""><![CDATA[
POST /restconf/operations
     /ietf-subscribed-notifications:modify-subscription

{
 "ietf-subscribed-notifications:input": {
    "id": 23,
    "ietf-yang-push:datastore-xpath-filter":
       "/example-module:foo/example-module:bar",
    "ietf-yang-push:periodic": {
       "ietf-yang-push:period": 500
    }
  }
} ]]></artwork>
          </figure>
          <t>If the publisher can satisfy both changes, the publisher sends a positive result for the RPC. If the publisher cannot satisfy either of the proposed changes, the publisher sends an RPC error response (e).  The following is an example RPC error response for (e) which that includes a hint. This hint is an alternative time period value which that might have resulted in a successful modification:</t>
          <figure align="center" anchor="negative-modify-subs" title="Modify subscription failure anchor="negative-modify-subs">
            <name>"modify-subscription" Failure with Hint (e)">
            <artwork><![CDATA[ (e)</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
HTTP status code - 400

{ "ietf-restconf:errors" : {
    "error" : [
      "error-type": "application",
      "error-tag": "invalid-value",
      "error-severity": "error",
      "error-app-tag": "ietf-yang-push:period-unsupported",
      "error-info": {
        "ietf-yang-push":
        "modify-subscription-datastore-error-info": {
           "period-hint": 3000
        }
      }
    ]
  }
} ]]></artwork>
          </figure>
        </section>
        <section title="Deleting numbered="true" toc="default">
          <name>Deleting Dynamic Subscriptions"> Subscriptions</name>
          <t>The following demonstrates deleting a subscription.  This subscription may have been to either a stream or a datastore.</t>
          <figure align="center" anchor="simple-delete-subs" title="Delete subscription"> anchor="simple-delete-subs">
            <name>"delete-subscription" Request</name>
            <artwork name="ex-delete-subscription.json"><![CDATA[ name="ex-delete-subscription.json" type="" align="left" alt=""><![CDATA[
POST /restconf/operations
     /ietf-subscribed-notifications:delete-subscription

{
 "delete-subscription": {
    "id": "22"
 }
} ]]></artwork>
          </figure>
          <t>If the publisher can satisfy the request, the publisher replies with success to the RPC request.</t>
          <t>If the publisher cannot satisfy the request, the publisher sends
	  an error-rpc &lt;rpc-error&gt; element indicating the modification didn't work. <xref target="negative-delete-subs"/>
	  target="negative-delete-subs" format="default"/> shows a valid
	  response for an existing valid subscription identifier, but that subscription identifier was created on a different transport session:</t>
          <figure align="center" anchor="negative-delete-subs" title="Unsuccessful delete subscription">
          <artwork><![CDATA[ anchor="negative-delete-subs">
            <name>Unsuccessful "delete-subscription"</name>
            <artwork name="" type="" align="left" alt=""><![CDATA[
HTTP status code - 404

{
  "ietf-restconf:errors" : {
    "error" : [
      "error-type": "application",
      "error-tag": "invalid-value",
      "error-severity": "error",
      "error-app-tag":
         "ietf-subscribed-notifications:no-such-subscription"
    ]
  }
} ]]></artwork>
          </figure>
        </section>
      </section>
      <section title="Subscription numbered="true" toc="default">
        <name>Subscription State Notifications"> Notifications</name>
        <t>A publisher will send subscription state notifications according to the definitions within <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/>).</t> target="RFC8639" format="default"/>.</t>
        <section title="subscription-modified"> numbered="true" toc="default">
          <name>"subscription-modified"</name>
          <t>A "subscription-modified" encoded in JSON would look like:</t>
          <figure align="center" anchor="subscription-modified-ctrl-plane-notif"
                title="subscription-modified subscription state notification">
            <artwork><![CDATA[ anchor="subscription-modified-ctrl-plane-notif">
            <name>"subscription-modified" Subscription State Notification</name>
            <sourcecode name="" type="json"><![CDATA[
{
  "ietf-restconf:notification" : {
    "eventTime": "2007-09-01T10:00:00Z",
    "ietf-subscribed-notifications:subscription-modified": {
      "id": 39,
      "uri": "https://example.com/restconf/subscriptions/22"
      "stream-xpath-filter": "/example-module:foo",
      "stream": {
         "ietf-netconf-subscribed-notifications" : "NETCONF"
      }
    }
  }
}
             ]]></artwork> ]]></sourcecode>
          </figure>
        </section>
        <section title="subscription-completed, subscription-resumed, numbered="true" toc="default">
          <name>"subscription-completed", "subscription-resumed", and replay-complete"> "replay-completed"</name>
          <t>A "subscription-completed" notification would look like:</t>
          <figure align="center"
                  anchor="subscription-completed"
                  title="subscription-completed notification in JSON">
            <artwork name="ex-subscription-completed.json"><![CDATA[ anchor="subscription-completed">
            <name>"subscription-completed" Notification in JSON</name>
            <sourcecode name="ex-subscription-completed.json" type="json"><![CDATA[
{
  "ietf-restconf:notification" : {
    "eventTime": "2007-09-01T10:00:00Z",
    "ietf-subscribed-notifications:subscription-completed": {
      "id": 39,
    }
  }
}
             ]]></artwork> ]]></sourcecode>
          </figure>
          <t>The "subscription-resumed" and "replay-complete" are virtually identical, with "subscription-completed" simply being replaced by "subscription-resumed" and "replay-complete".</t>
        </section>
        <section title="subscription-terminated numbered="true" toc="default">
          <name>"subscription-terminated" and subscription-suspended"> "subscription-suspended"</name>
          <t>A "subscription-terminated" would look like:</t>
          <figure align="center"
                  anchor="subscription-terminated"
                  title="subscription-terminated subscription state notification">
            <artwork name="ex-subscription-terminated.json"><![CDATA[ anchor="subscription-terminated">
            <name>"subscription-terminated" Subscription State Notification</name>
            <sourcecode name="ex-subscription-terminated.json" type="json"><![CDATA[
{
  "ietf-restconf:notification" : {
    "eventTime": "2007-09-01T10:00:00Z",
    "ietf-subscribed-notifications:subscription-terminated": {
      "id": 39,
      "error-id": "suspension-timeout"
    }
  }
}
            ]]></artwork> ]]></sourcecode>
          </figure>
          <t>The "subscription-suspended" is virtually identical, with "subscription-terminated" simply being replaced by "subscription-suspended".</t>
        </section>
      </section>
      <section title="Filter Example"> numbered="true" toc="default">
        <name>Filter Example</name>
        <t>This section provides an example which illustrate that illustrates the method of filtering event record contents.  The example is based on the YANG notification "vrrp-protocol-error-event" as defined per the ietf-vrrp.yang module within <xref target="RFC8347"/>. target="RFC8347" format="default"/>.  Event records based on this specification which that are generated by the publisher might appear as:</t>
        <figure align="center"
              anchor="VRRP-notification"
              title="RFC anchor="VRRP-notification">
          <name>RFC 8347 (VRRP) - Example Notification">
                  <artwork><![CDATA[ Notification</name>
          <artwork name="" type="" align="left" alt=""><![CDATA[
data: {
data:   "ietf-restconf:notification" : {
data:     "eventTime" : "2018-09-14T08:22:33.44Z",
data:     "ietf-vrrp:vrrp-protocol-error-event" : {
data:       "protocol-error-reason" : "checksum-error"
data:     }
data:   }
data: } ]]></artwork>
        </figure>
        <t>Suppose a subscriber wanted to establish a subscription which that only passes instances of event records where there is a "checksum-error" as part of a VRRP Virtual Router Redundancy Protocol (VRRP) protocol event.  Also assume the publisher places such event records into the NETCONF stream.  To get a continuous series of matching event records, the subscriber might request the application of an XPath filter against the NETCONF stream.  An "establish-subscription" RPC to meet this objective might be:</t>
        <figure align="center"
              anchor="VRRP-XPATH"
              title="Establishing anchor="VRRP-XPATH">
          <name>Establishing a subscription error reason Subscription Error Reason via XPath"> XPath</name>
          <artwork name="ex-establish-subscription-filter-xpath.json"><![CDATA[ name="ex-establish-subscription-filter-xpath.json" type="" align="left" alt=""><![CDATA[
POST /restconf/operations
     /ietf-subscribed-notifications:establish-subscription
{
   "ietf-subscribed-notifications:input": {
      "stream": "NETCONF",
      "stream-xpath-filter":
        "/ietf-vrrp:vrrp-protocol-error-event[
          protocol-error-reason='checksum-error']/",
   }
} ]]></artwork>
        </figure>
        <t>For more examples of XPath filters, see <xref target="XPATH"/>.</t> target="XPATH" format="default"/>.</t>
        <t>Suppose the "establish-subscription" in <xref target="VRRP-XPATH"/> target="VRRP-XPATH" format="default"/> was accepted. And suppose later a subscriber decided they wanted to broaden this subscription cover to all VRRP protocol events (i.e., not just those with a "checksum error").  The subscriber might attempt to modify the subscription in a way which that replaces the XPath filter with a subtree filter which that sends all VRRP protocol events to a subscriber. Such a "modify-subscription" RPC might look like:</t>

        <figure align="center"
              anchor="VRRP-Subtree"
              title=""> anchor="VRRP-Subtree">
<name>Example "modify-subscription" RPC</name>
          <artwork name="ex-modify-subscription-filter-subtree.json"><![CDATA[ name="ex-modify-subscription-filter-subtree.json" type="" align="left" alt=""><![CDATA[
POST /restconf/operations
     /ietf-subscribed-notifications:modify-subscription
{
   "ietf-subscribed-notifications:input": {
      "stream": "NETCONF",
      "stream-subtree-filter": {
        "/ietf-vrrp:vrrp-protocol-error-event" : {}
      }
   }
} ]]></artwork>
        </figure>
        <t>For more examples of subtree filters, see <xref target="RFC6241"/>, section 6.4.</t> target="RFC6241" sectionFormat="comma" section="6.4" format="default"/>.</t>
      </section>
    </section>

    <section title="Changes between revisions">
      <t>(To be removed by RFC editor prior to publication)</t>

      <t>v14 - v15</t>
          <t><list style="symbols">
            <t>Addressed review comments from Kent.</t>
        </list>
      </t>
      <t>v13 - v14</t>
          <t><list style="symbols">
            <t>Addressed review comments from IESG.</t>
        </list>
      </t>
      <t>v12 - v13</t>
          <t><list style="symbols">
            <t>Enhanced "error-tag" values based on SN review.</t>
        </list>
      </t>
      <t>v11 - v12</t>
          <t><list style="symbols">
            <t>Added text in 3.2 for expected behavior when ietf-restconf-monitoring.yang is also supported.</t>
            <t>Added section 2 to the reference to draft-ietf-netconf-nmda-restconf.</t>
            <t>Replaced kill-subscription-error by delete-subscription-error in section 3.3.</t>
            <t>Clarified vertical lines (a) and (b) in Figure 1 of section 3.4</t>
            <t>Section 3.4, 3rd bullet after Figure 1, replaced "must" with "MUST".</t>
            <t>Modified text in section 3.4 regarding access to RPCs modify-subscription, resync-subscription, delete-subscription and kill-subscription.</t>
            <t>Section 4, first bullet for HTTP2: replaced dscp and priority with weighting and weight.</t>
            <t>Section 6, added YANG tree diagram and fixed description of the module.</t>
            <t>Section 7, fixed indentation of module description statement.</t>
            <t>Section 7, in YANG module changed year in copyright statement to 2019.</t>
            <t>Section 8, added text on how server protects access numbered="false" toc="default">
      <name>Acknowledgments</name>
      <t>We wish to acknowledge the subscription URI.</t>
            <t>Fixed outdated references and removed unused references.</t>
            <t>Fixed the instances of line too long.</t>
            <t>Fixed example in Figure 3.</t>
        </list>
      </t>

      <t>v10 - v11</t>
          <t><list style="symbols">
            <t>Per Kent's request, added name attribute to artwork which need to be extracted</t>
        </list>
      </t>

      <t>v09 - v10</t>
          <t><list style="symbols">
            <t>Fixed typo for resync.</t>
            <t>Added text wrt RPC permissions helpful contributions, comments, and RESTCONF username.</t>
        </list>
      </t>

      <t>v08 - v09</t>
          <t><list style="symbols">
            <t>Addressed comments suggestions that were received during WGLC.</t>
        </list>
      </t>

      <t>v07 - v08</t>
          <t><list style="symbols">
            <t>Aligned with RESTCONF mechanism.</t>
            <t>YANG model: removed augment of subscription-started, added restconf transport.</t>
            <t>Tweaked Appendix A.1 to match draft-ietf-netconf-netconf-event-notifications-13.</t>
            <t>Added Appendix A.3 for filter example.</t>
        </list>
      </t>

      <t>v06 - v07</t>
          <t><list style="symbols">
            <t>Removed configured subscriptions.</t>
            <t>Subscription identifier renamed to id.</t>
        </list>
      </t>

      <t>v05 - v06</t>
          <t><list style="symbols">
            <t>JSON examples updated by Reshad.</t>
        </list>
      </t>

      <t>v04 - v05</t>
          <t><list style="symbols">
            <t>Error mechanisms updated to match embedded RESTCONF mechanisms</t>
            <t>Restructured format and sections of document.</t>
            <t>Added a YANG data model for HTTP specific parameters.</t>
            <t>Mirrored the examples from the NETCONF transport draft to allow easy comparison.</t>
        </list>
      </t>

      <t>v03 - v04</t>
          <t><list style="symbols">
            <t>Draft not fully synched to new version of subscribed-notifications yet.</t>
            <t>References updated</t>
        </list>
      </t>

      <t>v02 - v03</t>
          <t><list style="symbols">
            <t>Event notification reframed to notification message.</t>
            <t>Tweaks to wording/capitalization/format.</t>
        </list>
      </t>

      <t>v01 - v02</t>
      <t><list style="symbols">
            <t>Removed sections now redundant with <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> and <xref target="I-D.ietf-netconf-yang-push"/> such as:  mechanisms for subscription maintenance, terminology definitions, stream discovery.</t>
            <t>3rd party subscriptions are out-of-scope.</t>
            <t>SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions</t>
            <t>Timeframes for event tagging are self-defined.</t>
            <t>Clean-up of wording, references to terminology, section numbers.</t>
        </list>
      </t>

      <t>v00 - v01</t>
      <t><list style="symbols">
            <t>Removed the ability for more than one subscription to go to a single HTTP2 stream.</t>
            <t>Updated call flows.  Extensively.</t>
            <t>SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions</t>
            <t>HTTP is not used to determine that a receiver has gone silent and is not Receiving Event Notifications</t>
            <t>Many clean-ups of wording Ambika Prasad Tripathy, Alberto Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu, and terminology</t>
        </list>
      </t> Robert Wilton.</t>
    </section>
  </back>
</rfc>