]> Ericsson

jaime@iki.fi

Universität Bremen TZI

Postfach 330440 D-28359 Bremen Germany +49-421-218-63921 cabo@tzi.org

Internet CoRE Working Group 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 Status information for this document may be found at . Discussion of this document takes place on the core Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The Constrained Application Protocol (CoAP) 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). 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 (), 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 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 , multicast requests, or suppressed responses ; a document that illustrates those uses whatever notation it finds suitable. It does not change CoAP , and it does not define or alter any message encoding on the wire.

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.

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:

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 and and now in .The name EDN and its expansion is currently under discussion in the CBOR WG and might change.

Design Principles The notation follows five principles.

Familiar structure:

The notation follows HTTP message syntax 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.

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 .

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 ().

Notation A request is written as a request line, zero or more option lines, and an optional payload (). A response has the same structure with a response line in place of the request line ().

Request structure

Response structure

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 . The target is a composed path shown as a URI reference usually beginning with / (i.e., in absolute-path reference form, see ). Where the host and/or URI scheme is relevant, the full URI form is used, for example POST coap://broker.example.com/ps.

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 .

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.

Content-Format Annotation An option line for Content-Format or Accept carries the content-format number followed by the corresponding media type in parentheses: The number is the value a sender places on the wire; the parenthetical names the media type for the reader and for validation tooling (). 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 , which is not yet registered.

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 is written as the comma-separated EDN form, as in Variant 6 of .

JSON-based formats:

JSON.

Link-format:

CoRE Link Format .

Binary content beyond CBOR:

A hexadecimal dump using the h'...' notation of EDN .

The diagnostic payload of an error response () is written as a text string with no Content-Format annotation, as shown in . A payload line that exceeds the available width is folded using the convention of , so that a tool reconstructs the original payload by removing the folds before parsing.

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 :

Exchange with transport annotations for message type and token

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.

Grammar sketches the structure in ABNF . 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 .

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 line that is not an option line and precedes a start line is a label. Transport annotations () are free-form and are not required to be machine-parsed.

Examples The examples in this section use a single sensor, living-room-sensor, throughout. A GET on a resource that returns a plain-text representation:

GET with a text payload

A POST that creates a topic, carrying a CBOR payload in both directions:

POST creating a topic, with CBOR payloads

A FETCH that filters a collection, returning a CoRE Link Format response:

FETCH with a CBOR filter ]]>

An iPATCH that applies a partial update:

iPATCH applying a partial update

An Observe subscription and its first notification:

Observe subscription

Discovery of a broker through .well-known/core :

Discovery via .well-known/core ;rt="core.ps" ]]>

An ACE token request and response:

ACE token request and response

An error response carries a diagnostic payload as a text string, without a Content-Format annotation, as described in :

Error response with a diagnostic payload

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 and . The option lines follow the Name: value form used in . The blank line separating options from the payload follows HTTP message syntax . The Content-Format annotation, a number followed by a media type in parentheses, follows . CBOR payloads follow the commented EDN style used in and in CORECONF . Transport annotations use the terms of . presents the source notations in more detail and compares them along these dimensions.

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: 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. A block can reference a CDDL data definition so that the payload is checked for structure as well as well-formedness: 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 ) and round-trips it to and from bytes; and the cddl Ruby gem validates CBOR against a CDDL data definition.

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.

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.

References Normative References The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources. This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource. The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. The Constrained Application Protocol (CoAP) is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for small payloads from sensors and actuators; however, applications will need to transfer larger payloads occasionally -- for instance, for firmware updates. In contrast to HTTP, where TCP does the grunt work of segmenting and resequencing, CoAP is based on datagram transports such as UDP or Datagram Transport Layer Security (DTLS). These transports only offer fragmentation, which is even more problematic in constrained nodes and networks, limiting the maximum size of resource representations that can practically be transferred. Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options for transferring multiple blocks of information from a resource representation in multiple request-response pairs. In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers. Essentially, the Block options provide a minimal way to transfer larger representations in a block-wise fashion. A CoAP implementation that does not support these options generally is limited in the size of the representations that can be exchanged, so there is an expectation that the Block options will be widely used in CoAP implementations. Therefore, this specification updates RFC 7252. In many Internet of Things (IoT) applications, direct discovery of resources is not practical due to sleeping nodes or networks where multicast traffic is inefficient. These problems can be solved by employing an entity called a Resource Directory (RD), which contains information about resources held on other servers, allowing lookups to be performed for those resources. The input to an RD is composed of links, and the output is composed of links constructed from the information stored in the RD. This document specifies the web interfaces that an RD supports for web servers to discover the RD and to register, maintain, look up, and remove information on resources. Furthermore, new target attributes useful in conjunction with an RD are defined. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] Informative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. This document specifies a profile for the Authentication and Authorization for Constrained Environments (ACE) framework. It utilizes Object Security for Constrained RESTful Environments (OSCORE) to provide communication security and proof-of-possession for a key owned by the client and bound to an OAuth 2.0 access token. This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE-OAuth. The framework is based on a set of building blocks including OAuth 2.0 and the Constrained Application Protocol (CoAP), thus transforming a well-known and widely used authorization solution into a form suitable for IoT devices. Existing specifications are used where possible, but extensions are added and profiles are defined to better serve the IoT use cases. This document describes the Concise Binary Object Representation (CBOR) Sequence format and associated media type "application/cbor-seq". A CBOR Sequence consists of any number of encoded CBOR data items, simply concatenated in sequence. Structured syntax suffixes for media types allow other media types to build on them and make it explicit that they are built on an existing media type as their foundation. This specification defines and registers "+cbor-seq" as a structured syntax suffix for CBOR Sequences. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. Trilliant Networks Inc. consultant IMT Atlantique YumaWorks Universität Bremen TZI This document describes a network management interface for constrained devices and networks, called CoAP Management Interface (CORECONF). The Constrained Application Protocol (CoAP) is used to access datastore and data node resources specified in YANG, or SMIv2 converted to YANG. CORECONF uses the YANG to CBOR mapping and converts YANG identifier strings to numeric identifiers for payload size reduction. CORECONF extends the set of YANG based protocols, NETCONF and RESTCONF, with the capability to manage constrained devices and networks. Ericsson Dogtiger Labs Ericsson This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker. Universität Bremen TZI This document formalizes and consolidates the definition of the Concise Diagnostic Notation (CDN) of the Concise Binary Object Representation (CBOR), addressing implementer experience. Replacing CDN's previous informal descriptions, it updates RFC 8949, obsoleting its Section 8, and RFC 8610, obsoleting its Appendix G. It also specifies registry-based extension points and uses them to support text representations such as of epoch-based dates/times and of IP addresses and prefixes. // (This cref will be removed by the RFC editor:) -26 is intended to // address the May/June 2026 Working Group Last Call comments on -25 // and the ensuing WG discussions. Specifically, this update: • is // going further with the idea to entirely replace the non- backwards // compatible update considered for the RFC 8610/G.4 concatenation by // two new application extensions (temporarily named b1/t1), and to // add related application-oriented extensions that deprecate the // original streamstring syntax. • includes the float'' application- // extension so that the entire CBOR format can be covered. • now // uses rules closer to those of markdown for handling data // transparency in raw strings, simplifying their implementation. • // adds security considerations. • proactively reserves the // application-extension identifier "pragma" for potential future // standardization. • This update does not address certain comments // that propose some editorial restructuring requiring moving text // around; this is best done in a next revision after the technical // comments are addressed. There can be machine-to-machine (M2M) scenarios where server responses to client requests are redundant. This kind of open-loop exchange (with no response path from the server to the client) may be desired to minimize resource consumption in constrained systems while updating many resources simultaneously or performing high-frequency updates. CoAP already provides Non-confirmable (NON) messages that are not acknowledged by the recipient. However, the request/response semantics still require the server to respond with a status code indicating "the result of the attempt to understand and satisfy the request", per RFC 7252. This specification introduces a CoAP option called 'No-Response'. Using this option, the client can explicitly express to the server its disinterest in all responses against the particular request. This option also provides granular control to enable expression of disinterest to a particular response class or a combination of response classes. The server MAY decide to suppress the response by not transmitting it back to the client according to the value of the No-Response option in the request. This option may be effective for both unicast and multicast requests. This document also discusses a few examples of applications that benefit from this option. This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]

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 , embeds message sequence charts with message-layer detail:

Variant 1 (RFC 7252): message sequence chart with transport detail

Variant 2, from , shows the CoAP header as raw hexadecimal within numbered sequence diagrams:

Variant 2 (RFC 7641): compact hex header

Variant 3, from , uses Req:/Res: labels with the full URI on the first line:

Variant 3 (RFC 9176): Req/Res shorthand ;rt=temperature-c;if=sensor Res: 2.01 Created Location-Path: /rd/4521 ]]>

Variant 4, from , places the method and URI on the first line and lets the payload follow directly, with no explicit marker:

Variant 4 (RFC 8132): method + URI, payload follows

Variant 5, from , prefixes each message with Header: and each body with Payload:, and carries CBOR in diagnostic notation:

Variant 5 (RFC 9203): Header/Payload with CBOR diagnostic

Variant 6, from CORECONF , uses REQ:/RES: labels, an angle-bracketed path, and a parenthetical Content-Format:

Variant 6 (CORECONF): REQ/RES with angle-bracket path (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" } ]]>

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:

Variant 7 (CoAP pub-sub): 9203-style with path-only URI

compares the variants. Comparison of existing CoAP notation variants

Variant	First line	URI style	Payload marker	Payload format	Transport detail
1 (7252)	Header: GET (T=CON, Code=0.01, MID=...)	Split options	Payload: inline	Plain text	Yes
2 (7641)	Header: GET 0x...	Uri-Path option	Payload: inline	Plain text	Yes (hex)
3 (9176)	Req: POST coap://host/path	Full URI	Payload:	Link-format	No
4 (8132)	FETCH CoAP://host/path	Full URI	None (follows)	JSON	No
5 (9203)	Header: POST (Code=0.02)	Split options	Payload:	CBOR diagnostic	No
6 (COMI)	REQ: FETCH </path>	Path in <>	None (follows)	CBOR diagnostic	No
7 (pubsub)	Header: POST (Code=0.02)	Split options	Payload (...):	CBOR diagnostic	No

Three observations follow from the survey. Variants 5, 6, and 7 all carry CBOR diagnostic payloads but frame the surrounding message differently. Variants 3 and 4 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. TODO: Look at RFC 8323 and signaling codes (7.xx).

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.

Acknowledgements This notation distills conventions from , , , , , and CORECONF, and from discussion in the CoRE Working Group.