CoAP Diagnostic Message Notation
draft-jimenez-core-coap-diag-01
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Jaime Jimenez , Carsten Bormann | ||
| Last updated | 2026-11-02 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources |
GitHub Repository
|
||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| On agenda | core at IETF-127 | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-jimenez-core-coap-diag-01
CoRE Working Group J. Jimenez
Internet-Draft Ericsson
Intended status: Informational C. Bormann
Expires: 6 May 2027 Universität Bremen TZI
2 November 2026
CoAP Diagnostic Message Notation
draft-jimenez-core-coap-diag-01
Abstract
This document defines a text notation for representing Constrained
Application Protocol (CoAP) request/response exchanges in Internet-
Drafts and RFCs. The notation balances human readability with
mechanical validation: a reader can follow an exchange at a glance,
and tooling can be built to parse the message structure and check
each payload against its declared content format. The notation is
application-layer by default, with message-layer detail added only
where an example depends on it. It is a recommended convention for
use in documents and with authoring tools such as kramdown-rfc, not a
conformance target; it does not change CoAP or any on-the-wire
encoding.
About This Document
This note is to be removed before publishing as an RFC.
Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-jimenez-core-coap-diag/.
Discussion of this document takes place on the core Working Group
mailing list (mailto:core@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/core/. Subscribe at
https://www.ietf.org/mailman/listinfo/core/.
Source for this draft and an issue tracker can be found at
https://github.com/jaimejim/coap-diag.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Jimenez & Bormann Expires 6 May 2027 [Page 1]
Internet-Draft CoAP Diag November 2026
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 6 May 2027.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Design Principles . . . . . . . . . . . . . . . . . . . . . . 4
4. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.1. Request Line . . . . . . . . . . . . . . . . . . . . . . 5
4.2. Response Line . . . . . . . . . . . . . . . . . . . . . . 6
4.3. Options . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.4. Content-Format Annotation . . . . . . . . . . . . . . . . 6
4.5. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.6. Payload Representations . . . . . . . . . . . . . . . . . 7
4.7. Transport Annotations . . . . . . . . . . . . . . . . . . 8
4.8. Multiple Messages . . . . . . . . . . . . . . . . . . . . 8
4.9. Grammar . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Relationship to Existing Notations . . . . . . . . . . . . . 14
7. Tool Integration . . . . . . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 16
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.1. Normative References . . . . . . . . . . . . . . . . . . 16
10.2. Informative References . . . . . . . . . . . . . . . . . 17
Appendix A. Survey of Existing Notation Variants . . . . . . . . 19
Appendix B. Design Elements for a Unified Notation . . . . . . . 25
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25
Jimenez & Bormann Expires 6 May 2027 [Page 2]
Internet-Draft CoAP Diag November 2026
1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] defines a
request/response model in which clients send requests on resources
hosted by servers, receiving responses. Documents that specify or
use CoAP illustrate these exchanges with examples: a request line, a
set of options, and a payload, followed by the response. These
examples are how a reader first understands a protocol interaction,
and they are frequently the part of a document that implementers copy
from.
Authors write these examples in divergent, ad hoc notations. Some
split the request target into individual Uri-Path and Uri-Query
option lines; others compose it into a single URI on the first line.
Some prefix each message with Header: and each body with Payload:;
others use Req: and Res:, or no markers at all. The same CBOR
payload appears with and without a declared content format, and
response codes are written both as 2.05 Content and as Header:
Content (Code=2.05). Appendix A surveys seven such variants drawn
from published RFCs and active drafts.
This divergence has two costs. A reader who moves between documents
must re-learn the convention each time. More importantly, no widely
used notation is both readable and machine-checkable, so a malformed
CBOR or JSON payload in an example is caught only by a human
reviewer, if at all. Tooling that could validate payloads exists
(Section 7), but it needs a predictable structure to parse first.
This document defines a single notation for CoAP exchanges, for use
in documents and in authoring tools. The notation follows HTTP
message syntax [RFC9112] where practical, composes URIs on the first
line, declares the content format of each payload, and represents
payloads in the text notation appropriate to that format. It covers
requests, responses, and their options and payloads. It does not
define a rendering for transport mechanisms such as block-wise
transfer [RFC7959], multicast requests, or suppressed responses
[RFC7967]; a document that illustrates those uses whatever notation
it finds suitable. It does not change CoAP [RFC7252], and it does
not define or alter any message encoding on the wire.
2. Terminology
This document uses the following terms.
request line:
The first line of a request. It carries the text name for the
CoAP method and the request target, for example GET /temperature.
Jimenez & Bormann Expires 6 May 2027 [Page 3]
Internet-Draft CoAP Diag November 2026
response line:
The first line of a response. It carries the response code in
X.YY form and a reason phrase, for example 2.05 Content.
option line:
A line of the form Name: value that represents one CoAP option,
using the registered option name.
annotation:
Additional information added to a request, response, or option
line.
Content-Format annotation:
In an option line for the Content-Format (or Accept) option, the
content-format number is followed by its media type (and
parameters, if any) in parentheses, for example:
Content-Format: 60 (application/cbor)
payload:
The message body, separated from the option lines by a single
blank line and written in the text notation of its content format.
transport annotation:
An optional parenthetical on the request or response line that
records message-layer detail such as the message type or token,
for example (CON, Token=0x64).
EDN:
CBOR Diagnostic Notation, the text representation of CBOR data
items originally defined in Section 8 of [RFC8949] and Appendix G
of [RFC8610] and now in [I-D.ietf-cbor-edn-literals].
// The name EDN and its expansion is currently under discussion in
// the CBOR WG and might change.
3. Design Principles
The notation follows five principles.
Familiar structure:
The notation follows HTTP message syntax [RFC9112] where
practical, so that a reader accustomed to HTTP examples can read a
CoAP exchange without a legend.
Concise but unambiguous:
The notation omits redundant labels while keeping the structure
parsable. The method or response code, the options, and the
payload each occupy a distinct position.
Jimenez & Bormann Expires 6 May 2027 [Page 4]
Internet-Draft CoAP Diag November 2026
Payload-format-aware:
A payload is preceded by a Content-Format annotation that names
its media type, so that a tool can dispatch the payload to the
correct validator. The diagnostic payload of an error response is
the exception, as described in Section 4.5.
Wire-faithful:
Options are written with their registered CoAP names, and request
targets are composed into URIs rather than invented. The notation
reflects the protocol it illustrates.
Transport-agnostic by default:
The notation describes the application layer. CoAP message-layer
detail is added only where an example depends on it, using
transport annotations (Section 4.7).
4. Notation
A request is written as a request line, zero or more option lines,
and an optional payload (Figure 1). A response has the same
structure with a response line in place of the request line
(Figure 2).
METHOD /path[?query]
[Option: value]
[Option: value]
[payload]
Figure 1: Request structure
CODE Reason-Phrase
[Option: value]
[Option: value]
[payload]
Figure 2: Response structure
4.1. Request Line
The request line carries the CoAP method followed by the request
target. The method is written as its (mostly) uppercase name, for
example GET, POST, PUT, DELETE, FETCH, PATCH, or iPATCH [RFC8132].
The target is a composed path shown as a URI reference usually
beginning with / (i.e., in absolute-path reference form, see
Section 4.2 of [RFC3986]). Where the host and/or URI scheme is
relevant, the full URI form is used, for example POST
Jimenez & Bormann Expires 6 May 2027 [Page 5]
Internet-Draft CoAP Diag November 2026
coap://broker.example.com/ps.
4.2. Response Line
The response line carries the response code in X.YY form followed by
its reason phrase, for example 2.01 Created or 2.05 Content. The
reason phrase is the name registered for that code in the IANA
registry established in Section 12.1.2 of [RFC7252].
4.3. Options
Each option occupies one line of the form Name: value, using the
option name registered in the "CoAP Option Numbers" registry. Uri-
Path segments are composed into the target on the request line rather
than written as separate Uri-Path option lines, and Uri-Query
parameters are composed after a ?. Location options in a response are
composed in the same way and represented as an option line, for
example Location-Path: /ps/h9392.
4.4. Content-Format Annotation
An option line for Content-Format or Accept carries the content-
format number followed by the corresponding media type in
parentheses:
Content-Format: TBD606 (application/core-pubsub+cbor)
The number is the value a sender places on the wire; the
parenthetical names the media type for the reader and for validation
tooling (Section 7). Where a code point has not yet been assigned, a
placeholder is used in its place, written as TBDnnn or NNN, and
resolved once IANA assigns the value. The examples in this document
use TBD606 for the application/core-pubsub+cbor format defined in
[I-D.ietf-core-coap-pubsub], which is not yet registered.
4.5. Payload
A single blank line separates the last option line from the payload.
The payload is written in the text notation of its content format:
CBOR-based formats:
EDN, with inline comments where they aid the reader. A CBOR
sequence [RFC8742] is written as the comma-separated EDN form, as
in Variant 6 of Appendix A.
JSON-based formats:
JSON.
Jimenez & Bormann Expires 6 May 2027 [Page 6]
Internet-Draft CoAP Diag November 2026
Link-format:
CoRE Link Format [RFC6690].
Binary content beyond CBOR:
A hexadecimal dump using the h'...' notation of EDN [RFC8949].
Blank space and comments between the hex digits are permitted by
[I-D.ietf-cbor-edn-literals], so the dump can be grouped into
fields and annotated.
The diagnostic payload of an error response (Section 5.5.2 of
[RFC7252]) is written as a text string with no Content-Format
annotation, as shown in Figure 14.
A payload line that exceeds the available width is folded using the
convention of [RFC8792], so that a tool reconstructs the original
payload by removing the folds before parsing.
4.6. Payload Representations
The text notation given in Section 4.5 is the default representation
of a payload, and in the common case it is the only one shown. An
example departs from this in two situations. In the first, the
octets on the wire are the point of the example, for instance in a
document that defines an encoding, and the reader needs them next to
the readable form. In the second, the content format has no text
notation that a tool can parse but does have a human-readable
rendering. DNS over CoAP [RFC9953] meets both: its request examples
show a DNS message as a hexadecimal dump and in the presentation
style of DNS tooling, and its response examples show the latter
alone.
A representation other than the default is introduced by a
representation marker, a line of the form Payload (form): placed
where that representation begins. The default representation, when
shown, comes first and carries no marker. Two forms are defined:
hex:
The octets of the payload, written as an EDN byte string in h'...'
notation. For a CBOR-based format this is the encoding of the EDN
shown as the default representation.
text:
A human-readable rendering of the payload in a form established
for the content format, such as the DNS presentation style in
Figure 12. A text representation is for the reader; tooling does
not parse it.
Jimenez & Bormann Expires 6 May 2027 [Page 7]
Internet-Draft CoAP Diag November 2026
A blank line separates a marked representation from the one before
it. Figure 12 shows a request with the default and the text
representation, and a response with the text representation alone.
4.7. Transport Annotations
Where an example depends on CoAP message-layer behavior, the detail
is added in parentheses on the request or response line. Common
annotations record the message type (CON, NON, ACK), the token, and
the message ID, as defined in [RFC7252]:
GET /temperature (CON, Token=0x64)
2.05 Content (ACK)
Observe: 9
Max-Age: 15
Content-Format: 0 (text/plain)
22.3 Cel
Figure 3: Exchange with transport annotations for message type
and token
4.8. Multiple Messages
An exchange of more than two messages is written as a sequence of
requests and responses, each separated from the next by a blank line.
A short label can precede a message where it clarifies the flow.
4.9. Grammar
Figure 4 sketches the structure in ABNF [RFC5234]. The grammar is
descriptive: it fixes the lexical shape a tool relies on, not every
detail of the method names, option names, or payload syntax, which
are drawn from the documents cited in Section 6.
Jimenez & Bormann Expires 6 May 2027 [Page 8]
Internet-Draft CoAP Diag November 2026
message = start-line *option-line [blank-line payload]
start-line = (method SP request-target / code SP reason)
[SP annot] newline
option-line = option-name ":" SP option-value newline
blank-line = newline
annot = "(" *annot-text ")" ; free-form transport detail
payload = default-repr *(blank-line marked-repr)
/ marked-repr *(blank-line marked-repr)
marked-repr = repr-marker repr
repr-marker = %s"Payload (" form "):" newline
form = %s"hex" / %s"text"
method = 1*ALPHA ; e.g. GET, POST, iPATCH
request-target = path ["?" query] / absolute-URI
code = DIGIT "." 2DIGIT ; e.g. 2.05
Figure 4: Descriptive grammar of the notation
An option line uses a single space after the colon. The blank line
before a payload is present whenever a payload is present and omitted
otherwise. A payload extends to the blank line that precedes the
next start line or label, so a payload may itself contain blank
lines, as the DNS presentation style in Figure 12 does. A line that
is not an option line and precedes a start line is a label. The
representation forms default-repr and repr (Section 4.6) are written
in the notation of the content format and are not constrained by this
grammar. Transport annotations (Section 4.7) are free-form and are
not required to be machine-parsed.
5. Examples
The examples in this section use a single sensor, living-room-sensor,
throughout; the two DNS examples resolve a single name, example.org.
A GET on a resource that returns a plain-text representation:
GET /temperature
2.05 Content
Content-Format: 0 (text/plain)
22.3 Cel
Figure 5: GET with a text payload
A POST that creates a topic, carrying a CBOR payload in both
directions:
Jimenez & Bormann Expires 6 May 2027 [Page 9]
Internet-Draft CoAP Diag November 2026
POST /ps
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ topic-name /
0: "living-room-sensor",
/ resource-type /
2: "core.ps.data"
}
2.01 Created
Location-Path: /ps/h9392
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ topic-name /
0: "living-room-sensor",
/ topic-data /
1: "/ps/data/1bd0d6d",
/ resource-type /
2: "core.ps.data"
}
Figure 6: POST creating a topic, with CBOR payloads
A FETCH that filters a collection, returning a CoRE Link Format
response:
FETCH /ps
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ topic-name /
0: "living-room-sensor",
/ resource-type /
2: "core.ps.data"
}
2.05 Content
Content-Format: 40 (application/link-format)
</ps/2e3570>
Figure 7: FETCH with a CBOR filter
An iPATCH [RFC8132] that applies a partial update:
Jimenez & Bormann Expires 6 May 2027 [Page 10]
Internet-Draft CoAP Diag November 2026
iPATCH /ps/h9392
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ observer-check /
7: 7200
}
2.04 Changed
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ observer-check /
7: 7200
}
Figure 8: iPATCH applying a partial update
An Observe [RFC7641] subscription and its first notification:
GET /ps/data/1bd0d6d
Observe: 0
2.05 Content
Observe: 1234
Content-Format: 60 (application/cbor)
{
/ name /
0: "living-room-sensor",
/ value /
2: 22.5
}
Figure 9: Observe subscription
Discovery of a broker through .well-known/core [RFC6690]:
GET /.well-known/core?rt=core.ps
2.05 Content
Content-Format: 40 (application/link-format)
<coaps://broker.example.com/ps>;rt="core.ps"
Figure 10: Discovery via .well-known/core
An ACE [RFC9200] token request and response:
Jimenez & Bormann Expires 6 May 2027 [Page 11]
Internet-Draft CoAP Diag November 2026
POST /token
Content-Format: 19 (application/ace+cbor)
{
/ audience /
5: "living-room-sensor",
/ scope /
9: "read"
}
2.01 Created
Content-Format: 19 (application/ace+cbor)
{
/ access_token /
1: h'8343a1010aa1054d',
/ token_type /
34: 2,
/ profile /
38: 2 / coap_oscore /
}
Figure 11: ACE token request and response
A DNS query over CoAP [RFC9953] for the AAAA record of example.org.
The application/dns-message payload is binary, so its default
representation is a hexadecimal dump. The request adds the text
representation (Section 4.6) and the response shows only that
representation, as the examples in [RFC9953] do:
Jimenez & Bormann Expires 6 May 2027 [Page 12]
Internet-Draft CoAP Diag November 2026
FETCH coaps://[2001:db8::1]/
Content-Format: 553 (application/dns-message)
Accept: 553 (application/dns-message)
h'0000 0100 0001 0000 0000 0000 / header: ID 0, RD, QDCOUNT 1 /
07 6578616d706c65 03 6f7267 00 / example.org. /
001c 0001' / AAAA, IN /
Payload (text):
;; ->>Header<<- opcode: QUERY, status: NOERROR, id: 0
;; flags: rd; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;example.org. IN AAAA
2.05 Content
Content-Format: 553 (application/dns-message)
Max-Age: 58719
Payload (text):
;; ->>Header<<- opcode: QUERY, status: NOERROR, id: 0
;; flags: qr rd ad; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;example.org. IN AAAA
;; ANSWER SECTION:
;example.org. 79689 IN AAAA 2001:db8:1:0:1:2:3:4
Figure 12: DNS over CoAP query with two payload representations
The same query in the application/dns+cbor format of
[I-D.lenders-dns-cbor]. The payload is CBOR and is therefore written
in EDN, with no second representation needed. Constants such as the
record type are written with the e'' application extension of
[I-D.ietf-cbor-edn-e-ref], as [I-D.lenders-dns-cbor] does; in the
response the name, type, and class are elided because they follow
from the question:
Jimenez & Bormann Expires 6 May 2027 [Page 13]
Internet-Draft CoAP Diag November 2026
FETCH coaps://[2001:db8::1]/
Content-Format: TBD53 (application/dns+cbor)
Accept: TBD53 (application/dns+cbor)
[["example", "org", e'RR-AAAA']]
2.05 Content
Content-Format: TBD53 (application/dns+cbor)
Max-Age: 58719
[[79689, ip'2001:db8:1:0:1:2:3:4']]
Figure 13: The same query in application/dns+cbor
An error response carries a diagnostic payload as a text string,
without a Content-Format annotation, as described in Section 5.5.2 of
[RFC7252]:
GET /ps/data/unknown
4.04 Not Found
Unknown topic
Figure 14: Error response with a diagnostic payload
6. Relationship to Existing Notations
The notation composes elements that already appear in published
documents rather than inventing new ones. The request line follows
the method-and-URI form of [RFC8132] and [RFC9176]. The option lines
follow the Name: value form used in [RFC9203]. The blank line
separating options from the payload follows HTTP message syntax
[RFC9112]. The Content-Format annotation, a number followed by a
media type in parentheses, follows [RFC8132]. CBOR payloads follow
the commented EDN style used in [RFC9203] and in CORECONF
[I-D.ietf-core-comi]. Transport annotations use the terms of
[RFC7252].
Appendix A presents the source notations in more detail and compares
them along these dimensions.
7. Tool Integration
The notation is structured so that authoring tools can parse and
validate it. The mechanism below is one illustrative implementation,
in kramdown-rfc; the notation does not depend on a single toolchain.
In kramdown-rfc, an example is written in a coap sourcecode block:
Jimenez & Bormann Expires 6 May 2027 [Page 14]
Internet-Draft CoAP Diag November 2026
~~~ coap
POST /ps
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ topic-name /
0: "living-room-sensor",
/ resource-type /
2: "core.ps.data"
}
~~~
A tool processes such a block in four steps: it parses the structure
into the first line, the option lines, and the payload; it reads the
content-format number from the Content-Format annotation; it
dispatches the payload to a validator for that format, such as a CBOR
diagnostic parser for CBOR-based formats or a JSON parser for JSON-
based formats; and it reports any error with the line number within
the block.
Representation markers (Section 4.6) steer the same dispatch. The
default representation is validated as above. A hex representation
is parsed as an EDN byte string; where the tool has a decoder for the
content format, it decodes the octets, and where the block also shows
the default representation of a CBOR-based format, it checks that the
EDN encodes to the same octets. A text representation is skipped.
EDN application extensions in a payload, such as the e'' constants of
Figure 13, require their definitions to be available to the tool in
the same way a CDDL data definition is.
A block can reference a CDDL data definition so that the payload is
checked for structure as well as well-formedness:
~~~ coap
POST /ps
Content-Format: TBD606 (application/core-pubsub+cbor)
{
/ topic-name /
0: "living-room-sensor",
/ resource-type /
2: "core.ps.data"
}
~~~
{: check-cddl="pubsub-topic.cddl"}
Jimenez & Bormann Expires 6 May 2027 [Page 15]
Internet-Draft CoAP Diag November 2026
The building blocks for this validation already exist: kramdown-rfc
validates JSON sourcecode blocks and has hooks for CBOR diagnostic
types; the edn-abnf Ruby gem parses EDN (ABNF in
[I-D.ietf-cbor-edn-literals]) and round-trips it to and from bytes;
and the cddl Ruby gem validates CBOR against a CDDL data definition.
8. Security Considerations
This notation appears in documentation, not on the wire, and it
introduces no protocol behavior. It therefore adds no threat surface
to the protocols whose exchanges it illustrates.
Examples written in this notation are illustrative and are not
normative unless the surrounding document states otherwise. A reader
who copies an example into an implementation is responsible for
confirming that it matches the normative text.
Tooling that validates or executes example payloads processes input
taken from a document under edit. Such tooling treats the payloads
and any referenced CDDL data definition as untrusted input: a
malformed EDN payload or a hostile data definition affects only the
document build and does not reach a protocol endpoint.
9. IANA Considerations
This document has no IANA actions. The notation refers to CoAP
option names, response codes, and content-format numbers by the
values registered for them elsewhere; it defines no new code points,
media types, or registries.
10. References
10.1. Normative References
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/rfc/rfc6690>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/rfc/rfc7252>.
Jimenez & Bormann Expires 6 May 2027 [Page 16]
Internet-Draft CoAP Diag November 2026
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<https://www.rfc-editor.org/rfc/rfc7641>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016,
<https://www.rfc-editor.org/rfc/rfc7959>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/rfc/rfc8132>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/rfc/rfc8949>.
[RFC9176] Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and
P. van der Stok, "Constrained RESTful Environments (CoRE)
Resource Directory", RFC 9176, DOI 10.17487/RFC9176, April
2022, <https://www.rfc-editor.org/rfc/rfc9176>.
10.2. Informative References
[I-D.ietf-cbor-edn-e-ref]
Bormann, C., "External References to Values in CBOR
Diagnostic Notation (EDN)", Work in Progress, Internet-
Draft, draft-ietf-cbor-edn-e-ref-03, 1 March 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-cbor-
edn-e-ref-03>.
[I-D.ietf-cbor-edn-literals]
Bormann, C., "Concise Diagnostic Notation (CDN)", Work in
Progress, Internet-Draft, draft-ietf-cbor-edn-literals-29,
31 October 2026, <https://datatracker.ietf.org/doc/html/
draft-ietf-cbor-edn-literals-29>.
[I-D.ietf-core-coap-pubsub]
Jimenez, J., Koster, M., and A. Keränen, "A publish-
subscribe architecture for the Constrained Application
Protocol (CoAP)", Work in Progress, Internet-Draft, draft-
ietf-core-coap-pubsub-21, 2 July 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-core-
coap-pubsub-21>.
Jimenez & Bormann Expires 6 May 2027 [Page 17]
Internet-Draft CoAP Diag November 2026
[I-D.ietf-core-comi]
Veillette, M., Van der Stok, P., Pelov, A., Bierman, A.,
and C. Bormann, "CoAP Management Interface (CORECONF)",
Work in Progress, Internet-Draft, draft-ietf-core-comi-22,
2 November 2026, <https://datatracker.ietf.org/doc/html/
draft-ietf-core-comi-22>.
[I-D.lenders-dns-cbor]
Lenders, M. S., Bormann, C., Gütschow, M., Schmidt, T. C.,
and M. Wählisch, "A Concise Binary Object Representation
(CBOR) of DNS Messages", Work in Progress, Internet-Draft,
draft-lenders-dns-cbor-19, 2 November 2026,
<https://datatracker.ietf.org/doc/html/draft-lenders-dns-
cbor-19>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/rfc/rfc5234>.
[RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T.
Bose, "Constrained Application Protocol (CoAP) Option for
No Server Response", RFC 7967, DOI 10.17487/RFC7967,
August 2016, <https://www.rfc-editor.org/rfc/rfc7967>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/rfc/rfc8610>.
[RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR)
Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020,
<https://www.rfc-editor.org/rfc/rfc8742>.
[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
"Handling Long Lines in Content of Internet-Drafts and
RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
<https://www.rfc-editor.org/rfc/rfc8792>.
[RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
June 2022, <https://www.rfc-editor.org/rfc/rfc9112>.
Jimenez & Bormann Expires 6 May 2027 [Page 18]
Internet-Draft CoAP Diag November 2026
[RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for
Constrained Environments Using the OAuth 2.0 Framework
(ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022,
<https://www.rfc-editor.org/rfc/rfc9200>.
[RFC9203] Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson,
"The Object Security for Constrained RESTful Environments
(OSCORE) Profile of the Authentication and Authorization
for Constrained Environments (ACE) Framework", RFC 9203,
DOI 10.17487/RFC9203, August 2022,
<https://www.rfc-editor.org/rfc/rfc9203>.
[RFC9953] Lenders, M. S., Amsüss, C., Gündoğan, C., Schmidt, T. C.,
and M. Wählisch, "DNS over CoAP (DoC)", RFC 9953,
DOI 10.17487/RFC9953, March 2026,
<https://www.rfc-editor.org/rfc/rfc9953>.
Appendix A. Survey of Existing Notation Variants
The notation in this document distills the conventions found in
published RFCs and active drafts. This appendix records those source
notations. Each is shown with a representative exchange and a one-
line characterization.
Variant 1, from [RFC7252], embeds message sequence charts with
message-layer detail:
Header: GET (T=CON, Code=0.01, MID=0x7d34)
Token: 0x20
Uri-Path: "temperature"
Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34)
Token: 0x20
Payload: "22.3 C"
Figure 15: Variant 1 (RFC 7252): message sequence chart with
transport detail
Variant 2, from [RFC7641], shows the CoAP header as raw hexadecimal
within numbered sequence diagrams:
Jimenez & Bormann Expires 6 May 2027 [Page 19]
Internet-Draft CoAP Diag November 2026
Header: GET 0x41011633
Token: 0x4a
Uri-Path: temperature
Observe: 0 (register)
Header: 2.05 0x61451633
Token: 0x4a
Observe: 9
Max-Age: 15
Payload: "18.5 Cel"
Figure 16: Variant 2 (RFC 7641): compact hex header
Variant 3, from [RFC9176], uses Req:/Res: labels with the full URI on
the first line:
Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40
Payload: </sensors/temp>;rt=temperature-c;if=sensor
Res: 2.01 Created
Location-Path: /rd/4521
Figure 17: Variant 3 (RFC 9176): Req/Res shorthand
Variant 4, from [RFC8132], places the method and URI on the first
line and lets the payload follow directly, with no explicit marker:
FETCH CoAP://www.example.com/object
Content-Format: NNN (application/example-map-keys+json)
Accept: application/json
[ "foo" ]
2.05 Content
Content-Format: 50 (application/json)
{ "foo": ["bar","baz"] }
Figure 18: Variant 4 (RFC 8132): method + URI, payload follows
Variant 5, from [RFC9203], prefixes each message with Header: and
each body with Payload:, and carries CBOR in diagnostic notation:
Jimenez & Bormann Expires 6 May 2027 [Page 20]
Internet-Draft CoAP Diag November 2026
Header: POST (Code=0.02)
Uri-Host: "as.example.com"
Uri-Path: "token"
Content-Format: application/ace+cbor
Payload:
{
/ audience /
5 : "tempSensor4711",
/ scope /
9 : "read"
}
Figure 19: Variant 5 (RFC 9203): Header/Payload with CBOR diagnostic
Variant 6, from CORECONF [I-D.ietf-core-comi], uses REQ:/RES: labels,
an angle-bracketed path, and a parenthetical Content-Format:
REQ: FETCH </c>
(Content-Format: application/yang-identifiers+cbor-seq)
1723, / current-datetime (SID 1723) /
[1533, "eth0"] / interface (SID 1533) with name = "eth0" /
RES: 2.05 Content
(Content-Format: application/yang-instances+cbor-seq)
{ 1723 : "2014-10-26T12:16:31Z" }
Figure 20: Variant 6 (CORECONF): REQ/RES with angle-bracket path
Variant 7, from the CoAP publish-subscribe work, follows the Variant
5 form with a path-only target and annotates the payload line with a
format hint:
Jimenez & Bormann Expires 6 May 2027 [Page 21]
Internet-Draft CoAP Diag November 2026
Header: POST (Code=0.02)
Uri-Path: "ps"
Content-Format: TBD606 (application/core-pubsub+cbor)
Payload (in CBOR diagnostic notation):
{
/ topic-name /
0: "living-room-sensor",
/ resource-type /
2: "core.ps.data"
}
Header: Created (Code=2.01)
Location-Path: "ps"
Location-Path: "h9392"
Content-Format: TBD606 (application/core-pubsub+cbor)
Payload (in CBOR diagnostic notation):
{
/ topic-name /
0: "living-room-sensor",
/ topic-data /
1: "/ps/data/1bd0d6d",
/ resource-type /
2: "core.ps.data"
}
Figure 21: Variant 7 (CoAP pub-sub): 9203-style with path-only URI
Variant 8, from DNS over CoAP [RFC9953], follows the Variant 4 form
and labels each representation of the payload, showing a binary
payload as a hexadecimal dump and in a human-readable form, with the
latter alone in responses. An empty payload is marked [no payload]:
Jimenez & Bormann Expires 6 May 2027 [Page 22]
Internet-Draft CoAP Diag November 2026
FETCH coaps://[2001:db8::1]/
Content-Format: 553 (application/dns-message)
Accept: 553 (application/dns-message)
Payload (binary):
00 00 01 00 00 01 00 00 00 00 00 00 07 65 78 61
6d 70 6c 65 03 6f 72 67 00 00 1c 00 01
Payload (human-readable):
;; ->>Header<<- opcode: QUERY, status: NOERROR, id: 0
;; flags: rd; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;example.org. IN AAAA
2.05 Content
Content-Format: 553 (application/dns-message)
Max-Age: 58719
Payload (human-readable):
;; ->>Header<<- opcode: QUERY, status: NOERROR, id: 0
;; flags: qr rd ad; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;example.org. IN AAAA
;; ANSWER SECTION:
;example.org. 79689 IN AAAA 2001:db8:1:0:1:2:3:4
Figure 22: Variant 8 (RFC 9953): labeled payload representations
Table 1 compares the variants.
Jimenez & Bormann Expires 6 May 2027 [Page 23]
Internet-Draft CoAP Diag November 2026
+========+=============+=======+==============+==========+=========+
|Variant |First line |URI |Payload marker|Payload |Transport|
| | |style | |format |detail |
+========+=============+=======+==============+==========+=========+
|1 (7252)|Header: GET |Split |Payload: |Plain text|Yes |
| |(T=CON, |options|inline | | |
| |Code=0.01, | | | | |
| |MID=...) | | | | |
+--------+-------------+-------+--------------+----------+---------+
|2 (7641)|Header: GET |Uri- |Payload: |Plain text|Yes (hex)|
| |0x... |Path |inline | | |
| | |option | | | |
+--------+-------------+-------+--------------+----------+---------+
|3 (9176)|Req: POST |Full |Payload: |Link- |No |
| |coap://host/ |URI | |format | |
| |path | | | | |
+--------+-------------+-------+--------------+----------+---------+
|4 (8132)|FETCH |Full |None (follows)|JSON |No |
| |CoAP://host/ |URI | | | |
| |path | | | | |
+--------+-------------+-------+--------------+----------+---------+
|5 (9203)|Header: POST |Split |Payload: |CBOR |No |
| |(Code=0.02) |options| |diagnostic| |
+--------+-------------+-------+--------------+----------+---------+
|6 (COMI)|REQ: FETCH |Path in|None (follows)|CBOR |No |
| |</path> |<> | |diagnostic| |
+--------+-------------+-------+--------------+----------+---------+
|7 |Header: POST |Split |Payload (...):|CBOR |No |
|(pubsub)|(Code=0.02) |options| |diagnostic| |
+--------+-------------+-------+--------------+----------+---------+
|8 (9953)|FETCH |Full |Payload (...):|Hex and |No |
| |coaps://host/|URI |per |human- | |
| |path | |representation|readable | |
+--------+-------------+-------+--------------+----------+---------+
Table 1: Comparison of existing CoAP notation variants
Four observations follow from the survey. Variants 5, 6, and 7 all
carry CBOR diagnostic payloads but frame the surrounding message
differently. Variants 3, 4, and 8 are the closest to HTTP message
syntax, while Variants 5 and 7 are the most structured and the most
amenable to mechanical parsing. Only Variants 1 and 2 include
message-layer information; the remaining variants describe the
application layer alone. Variant 8 is the only one to show a payload
in more than one representation; Section 4.6 adopts that device, with
the marker reserved for a representation other than the default.
Jimenez & Bormann Expires 6 May 2027 [Page 24]
Internet-Draft CoAP Diag November 2026
// TODO: Look at RFC 8323 and signaling codes (7.xx).
Appendix B. Design Elements for a Unified Notation
The survey yields five design elements, which the notation in the
body satisfies:
1. A first line that identifies the method for a request or the
response code for a response, optionally with the URI.
2. Option lines as Name: value pairs.
3. An explicit separator between options and payload.
4. A declared payload format, as a Content-Format value or
annotation, so that a tool can validate the payload.
5. A payload in the text notation appropriate to that format: CBOR
EDN, JSON, link-format, or a hexadecimal dump, with a further
representation marked where the octets matter or the format has a
human-readable rendering.
Acknowledgements
This notation distills conventions from [RFC7252], [RFC7641],
[RFC8132], [RFC9176], [RFC9203], and CORECONF, and from discussion in
the CoRE Working Group.
Authors' Addresses
Jaime Jimenez
Ericsson
Email: jaime@iki.fi
Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Jimenez & Bormann Expires 6 May 2027 [Page 25]