Skip to content

Add support for yang-data+xml and yang-data+json #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mjethanandani wants to merge 3 commits into
base: v16
Choose a base branch
from
Open

Add support for yang-data+xml and yang-data+json #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
471970e
Add support for yang-data+xml and yang-data+json
mjethanandani May 10, 2026
c43bddd
Merge v16
mjethanandani Jun 9, 2026
f4dd8a3
Address Alex's comment
mjethanandani Jun 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 193 additions & 52 deletions draft/draft-ietf-netconf-https-notif.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,20 @@
target="RFC9114"> HTTP/3</xref>, support for it is considered
out of scope of this document at this time.</t>

<t>This document defines support for JSON and XML content;
future efforts may define support for other encodings (e.g.,
binary). This document requires that the publisher is a "server"
(e.g., a NETCONF or RESTCONF server), but does not assume that
the receiver is a NETCONF or RESTCONF server. It does expect
the receiver to be an HTTPS server to receive the
notifications.</t>
<t>
This document defines support for JSON and XML content, using
the media types defined in <xref
target="RFC8040">RESTCONF</xref>; future efforts may define
support for other encodings (e.g., CBOR). This document also
defines optional support for sending legacy notifications as
defined in <xref target="RFC5277">NETCONF Event
Notifications</xref> using "application/xml" as the media
type. This document requires that the publisher is a "server"
(e.g., a NETCONF or RESTCONF server), but does not assume that
the receiver is a NETCONF or RESTCONF server. It does expect
the receiver to be an HTTPS server to receive the
notifications.
</t>

<t>This document also defines two <xref target="RFC7950">YANG
1.1</xref> modules that extend the data model defined in <xref
Expand Down Expand Up @@ -232,30 +239,29 @@
<t>
To learn the capabilities of a receiver, a publisher can
issue an HTTPS GET request to the "capabilities" resource
(see <xref target= "overview"/>) on the receiver with
"Accept" header set using the "application/xml" as defined
in <xref target="RFC7303">XML Media Types</xref>, and/or
"application/json" as defined in <xref
target="RFC8259">JSON</xref> media-types.
(see <xref target= "overview"/>) on the receiver with the
"Accept" header set to "application/yang-data+xml" and/or
"application/yang-data+json", as defined in
<xref target="RFC8040">RESTCONF</xref>.
</t>
</section>
<section title="Response">
<t>The receiver responds with a "200 (OK)" message, having the
"Content-Type" header set to either "application/xml" or
"application/json" (which ever was selected), and containing
"Content-Type" header set to either "application/yang-data+xml" or
"application/yang-data+json" (whichever was selected), and containing
in the response body a list of the receiver's capabilities
encoded in the selected format.</t>
<t>Even though a YANG module is not defined for this interaction,
the response body MUST conform to the following YANG-modeled
format:</t>
<t>The response body MUST conform to the "receiver-capabilities"
structure defined in the "ietf-https-notif-transport" YANG module
(see <xref target="RFC8791">YANG Data Structure Extensions</xref>):</t>
<t>
<figure>
<artwork>container receiver-capabilities {
<artwork>structure receiver-capabilities {
description
"A container for a list of capabilities supported by
the receiver.";
"A structure defining the response body for the capabilities
GET request.";
leaf-list receiver-capability {
type "inet:uri";
type inet:uri;
description
"A capability supported by the receiver. A partial list of
capabilities is defined in the 'Capabilities for HTTPS
Expand All @@ -280,11 +286,11 @@
<figure>
<artwork><![CDATA[GET /some/path/capabilities HTTP/1.1
Host: example.com
Accept: application/xml, application/json;q=0.5]]></artwork>
Accept: application/yang-data+xml, application/yang-data+json;q=0.5]]></artwork>
</figure>
</t>
<t>If the receiver is able to reply using "application/xml", and
assuming it is able to receive JSON and XML encoded notifications,
<t>If the receiver is able to reply using "application/yang-data+xml",
and assuming it is able to receive JSON and XML encoded notifications,
and it is able to process the RFC 8639 state machine, the
response might look like this:</t>
<t>
Expand All @@ -293,40 +299,41 @@ Accept: application/xml, application/json;q=0.5]]></artwork>
Date: Wed, 26 Feb 2020 20:33:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/xml
Content-Type: application/yang-data+xml

<receiver-capabilities>
<receiver-capability>\
urn:ietf:capability:https-notif-receiver:encoding:json\
<receiver-capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-https-notif-transport">
<receiver-capability>
urn:ietf:params:yang-notif:https-capability:encoding:json
</receiver-capability>
<receiver-capability>\
urn:ietf:capability:https-notif-receiver:encoding:xml\
<receiver-capability>
urn:ietf:params:yang-notif:https-capability:encoding:xml
</receiver-capability>
<receiver-capability>\
urn:ietf:capability:https-notif-receiver:sub-notif\
<receiver-capability>
urn:ietf:params:yang-notif:https-capability:sub-notif
</receiver-capability>
</receiver-capabilities>]]></artwork>
</figure>
</t>
<t>If the receiver is unable to reply using "application/xml", the
response might look like this:</t>
<t>If the receiver is unable to reply using "application/yang-data+xml",
the response might look like this:</t>
<t>
<figure>
<artwork><![CDATA[HTTP/1.1 200 OK
Date: Wed, 26 Feb 2020 20:33:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/json
Content-Type: application/yang-data+json
Content-Length: nnn

{
"receiver-capabilities": {
"receiver-capability": [
"urn:ietf:capability:https-notif-receiver:encoding:json",
"urn:ietf:capability:https-notif-receiver:encoding:xml",
"urn:ietf:capability:https-notif-receiver:sub-notif"
]
}
"ietf-https-notif-transport:receiver-capabilities": {
"receiver-capability": [
"urn:ietf:params:yang-notif:https-capability:encoding:json",
"urn:ietf:params:yang-notif:https-capability:encoding:xml",
"urn:ietf:params:yang-notif:https-capability:sub-notif"
]
}
}]]></artwork>
</figure>
</t>
Expand All @@ -339,9 +346,9 @@ Content-Length: nnn
The publisher sends an HTTP POST request to the
"relay-notification" resource (see <xref target=
"overview"/>) on the receiver with the "Content-Type" header
set to either "application/json" or "application/xml" and a
body containing the notification encoded using the specified
format.
set to either "application/yang-data+json" or
"application/yang-data+xml" and a body containing the
notification encoded using the specified format.
</t>
<t>XML-encoded notifications are encoded using the format defined
by <xref target="RFC5277">NETCONF Event Notifications</xref>
Expand Down Expand Up @@ -374,7 +381,7 @@ Content-Length: nnn
<figure>
<artwork><![CDATA[POST /some/path/relay-notification HTTP/1.1
Host: example.com
Content-Type: application/xml
Content-Type: application/yang-data+xml

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2019-03-22T12:35:00Z</eventTime>
Expand All @@ -392,7 +399,7 @@ Content-Type: application/xml
<t><figure>
<artwork><![CDATA[POST /some/path/relay-notification HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Type: application/yang-data+json

{
"ietf-https-notif:notification": {
Expand All @@ -419,6 +426,131 @@ Server: example-server]]></artwork>
</section>
</section>

<section title="Support for Legacy Notifications (RFC 5277)">
<t>
This document primarily defines a transport for YANG
notifications. However, implementations MAY also use this
HTTPS-based transport to send legacy event notifications as
defined in <xref target="RFC5277">NETCONF Event
Notifications</xref>. This section defines how such legacy
notifications are sent and how a receiver advertises support
for them.
</t>

<section title="Request">
<t>
When sending legacy RFC 5277 notifications, the publisher
sends an HTTP POST request to the "relay-notification"
resource (see <xref target="overview"/>) with the
"Content-Type" header set to "application/xml". The body
MUST contain the notification encoded as defined in <xref
target="RFC5277">NETCONF Event Notifications</xref>.
</t>
</section>

<section title="Capabilities">
<t>
A receiver that supports legacy RFC 5277 notifications MUST
advertise this capability by including the following URI in
its capabilities response (see <xref
target="overview"/>):
</t>
<t>
<figure>
<artwork>urn:ietf:params:yang-notif:https-capability:rfc5277-notif</artwork>
</figure>
</t>

<t>
A publisher that intends to send legacy notifications SHOULD
query the receiver's capabilities first and MUST only send
RFC 5277 notifications when this capability URI is present.
</t>
<t>
A YANG-aware publisher SHOULD issue the capabilities request
with an "Accept" header set to "application/yang-data+xml"
and/or "application/yang-data+json", as described in <xref
target="overview"/>. A legacy publisher that only understands
"application/xml" MAY instead set the "Accept" header to
"application/xml". In that case, the receiver SHOULD respond
with "Content-Type: application/xml" and the same
"receiver-capabilities" XML structure, allowing the legacy
publisher to parse the capability URIs without requiring
knowledge of YANG media types.
</t>
</section>

<section title="Example">
<t>A legacy publisher that only understands "application/xml"
can discover receiver capabilities as follows:</t>
<t>
<figure>
<artwork><![CDATA[GET /some/path/capabilities HTTP/1.1
Host: example.com
Accept: application/xml]]></artwork>
</figure>
</t>
<t>
The receiver, recognizing that the publisher sent
"Accept: application/xml", responds with the same
"receiver-capabilities" structure but using
"Content-Type: application/xml":
</t>
<t>
<figure>
<artwork><![CDATA[HTTP/1.1 200 OK
Date: Wed, 26 Feb 2020 20:33:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/xml

<receiver-capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-https-notif-transport">
<receiver-capability>
urn:ietf:params:yang-notif:https-capability:encoding:json
</receiver-capability>
<receiver-capability>
urn:ietf:params:yang-notif:https-capability:encoding:xml
</receiver-capability>
<receiver-capability>
urn:ietf:params:yang-notif:https-capability:rfc5277-notif
</receiver-capability>
</receiver-capabilities>]]></artwork>
</figure>
</t>
<t>
Having confirmed the "rfc5277-notif" capability, the legacy
publisher then sends a notification as follows:
</t>
<t>
<figure>
<artwork><![CDATA[POST /some/path/relay-notification HTTP/1.1
Host: example.com
Content-Type: application/xml

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2019-03-22T12:35:00Z</eventTime>
<event xmlns="https://example.com/example-mod">
<event-class>fault</event-class>
<reporting-entity>
<card>Ethernet0</card>
</reporting-entity>
<severity>major</severity>
</event>
</notification>]]></artwork>
</figure>
</t>
<t>And the response on success might be as follows:</t>
<t>
<figure>
<artwork><![CDATA[HTTP/1.1 204 No Content
Date: Wed, 26 Feb 2020 20:33:30 GMT
Server: example-server]]></artwork>
</figure>
</t>
</section>
</section>

<section title='The "ietf-subscribed-notif-receivers" Module'>
<section title="Data Model Overview">
<t>This YANG module augments the "ietf-subscribed-notifications" module to
Expand Down Expand Up @@ -474,11 +606,15 @@ INSERT_TEXT_FROM_FILE(../bin/[email protected],
</section>

<section title="YANG module">
<t>The YANG module imports
<t>The YANG module imports
<xref target="RFC9911">Common YANG Data Types</xref>,
<xref target="RFC7407">A YANG Data Model for SNMP Configuration</xref>,
<xref target="RFC8639">Subscription to YANG Notifications</xref>,
<xref target="RFC8791">YANG Data Structure Extensions</xref>,
<!--<xref target="I-D.ietf-subscribed-notif-receivers">An HTTPS-based Transport for Configured Subscriptions</xref>,-->
and <xref target="I-D.ietf-netconf-http-client-server">YANG Groupings for HTTP Clients and HTTP Servers</xref>.</t>
and <xref target="I-D.ietf-netconf-http-client-server">YANG Groupings for HTTP Clients and HTTP Servers</xref>.
It also defines the "receiver-capabilities" structure used as
the response body of the capabilities GET request.</t>

<t>The YANG module is shown below.</t>

Expand Down Expand Up @@ -693,6 +829,12 @@ Record:
Description: Identifies support for state machine described in
RFC 8639, enabling the publisher to send, e.g., the
"subscription-started" notification.
Record:
URN: urn:ietf:params:yang-notif:https-capability:rfc5277-notif
Reference: RFC XXXX:An HTTPS-based Transport for YANG Notifications
Description: Identifies support for receiving legacy RFC 5277
XML notifications, transmitted using "application/xml"
as the Content-Type header value.
</artwork>
</figure>
</t>
Expand All @@ -710,24 +852,23 @@ Record:
<?rfc include='reference.RFC.6020.xml'?>
<?rfc include='reference.RFC.6241.xml'?>
<?rfc include='reference.RFC.6242.xml'?>
<?rfc include='reference.RFC.7303.xml'?>
<?rfc include='reference.RFC.7407.xml'?>
<?rfc include='reference.RFC.7950.xml'?>
<?rfc include='reference.RFC.8040.xml'?>
<?rfc include='reference.RFC.8174.xml'?>
<?rfc include='reference.RFC.8259.xml'?>
<?rfc include='reference.RFC.8340.xml'?>
<?rfc include='reference.RFC.8341.xml'?>
<?rfc include='reference.RFC.8446.xml'?>
<?rfc include='reference.RFC.8639.xml'?>
<?rfc include='reference.RFC.8791.xml'?>
<?rfc include='reference.RFC.9110.xml'?>
<?rfc include='reference.RFC.9112.xml'?>
<?rfc include='reference.RFC.9113.xml'?>
<?rfc include='reference.RFC.9114.xml'?>
<?rfc include='reference.RFC.9325.xml'?>
<?rfc include='reference.RFC.9645.xml'?>
<?rfc include='reference.RFC.9911.xml'?>
<?rfc include='reference.I-D.ietf-netconf-http-client-server.xml'?>

</references>
<references title="Informative references">
<?rfc include='reference.RFC.8141.xml'?>
Expand Down
Loading