]> Ericsson

Finland jaime@iki.fi

Dogtiger Labs

United States of America michaeljohnkoster@gmail.com

Ericsson

Finland ari.keranen@ericsson.com

Web and Internet Transport CoRE Working Group 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. 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) supports machine-to-machine communication across networks of constrained devices and constrained networks. CoAP uses a request/response model where clients make requests to servers in order to request actions on resources. Depending on the situation, the same device may act either as a server, a client, or both. One important class of constrained devices includes devices that are intended to run for years from a small battery, or by scavenging energy from their environment. These devices have limited up-time because they spend most of their time in a sleeping state with no network connectivity. Another important class of nodes are devices with limited reachability due to middle-boxes like Network Address Translators (NATs) and firewalls. For these nodes, the client/server-oriented architecture of REST can be challenging when interactions are not initiated by the devices themselves. A publish/subscribe-oriented architecture where nodes exchange data via topics through a broker entity might fit these nodes better. This document applies the idea of broker-based publish-subscribe to Constrained RESTful Environments using CoAP. It defines a broker that allows to create, discover, subscribe, and publish on topics.

Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in () () when, and only when, they appear in all capitals, as shown here. This specification requires readers to be familiar with all the terms and concepts that are discussed in and . Readers should also be familiar with the terms and concepts discussed in , , and . This specification makes use of the following terminology:

publish-subscribe (pubsub):

A message communication model where messages associated with specific topics are sent to a broker. Interested parties, i.e., subscribers, receive these topic-based messages from the broker without the original sender knowing the recipients. The broker handles the dispatching of these messages to the appropriate subscribers.

publishers and subscribers:

CoAP clients can act as publishers or as subscribers. Publishers send CoAP messages (publications) to the broker on specific topics. Subscribers have an ongoing relation (subscription) to a topic via CoAP Observe . Both roles operate without any mutual knowledge, guided by their respective topic interests.

topic collection:

A topic collection is hosted as one collection resource at the broker. A collection resource is a resource that contains links to other resources that a client can add or remove; that concept is described more generally in .

topic:

A set of information about an entity at the broker, including its configuration and other metadata. A topic is hosted as one topic resource at the broker, whose representation is the set of topic properties concerning the topic. All the topic resources associated with the same topic collection share a common base URI, i.e., the URI of the topic collection resource.

topic property:

A single element of configuration information that is associated with a topic.

topic-data resource:

A resource where clients can publish data and/or subscribe to data for a specific topic. The representation of the topic resource corresponding to such a topic also specifies the URI to the present topic-data resource.

broker:

A CoAP server component that hosts one or more topic collections with their topics, together with the topic-data resources of those topics. The broker is responsible for the store-and-forward of state update representations and for handling the topic lifecycle as defined in . A topic-data resource may be served from a different address than the topic resource, e.g., by a server that is part of the same broker deployment. The creation, configuration, and discovery of topics at a broker is specified in .

CoAP Publish-Subscribe Architecture shows a simple publish-subscribe architecture based on CoAP. The broker can create its hosted topics and set their initial configurations. Alternatively, topics can be created together with their initial configuration by a client (e.g., a publisher or a dedicated administrator), over the RESTful interface of the topic collection resource hosted by the broker. The broker is responsible for the store-and-forward of state update representations between CoAP clients. Publishers submit their data over the RESTful interface of the topic-data resource corresponding to the topic, hosted by the broker. Subscribers to a topic are notified of new publications by using Observe on the corresponding topic-data resource. As CoAP PubSub builds on and , its messages are not events but state updates following the principle of eventual consistency rather than per-event delivery. A message may be silently coalesced when a newer message on the same topic is delivered (e.g. by intermediaries or libraries), or be delivered twice, without changing the semantics. Applications requiring stronger guarantees need to handle that explicitly.

Publish-subscribe architecture based on CoAP + +---------->| subscriber | | | | +---------->| | '-----------' | | '------------' ... | broker | ... ... | | ... .-----------. | | observe .------------. | | publish | |<----------+ | | publisher +--------->| +---------->| subscriber | | | | +---------->| | '-----------' '----------' '------------' ]]>

Note that CoAP clients that merely interact with topic configuration but not with topic data (e.g., a dedicated administrator) are not depicted in . This document describes two sets of interactions; interactions to configure topics and their lifecycle (see and ) and interactions about the topic-data (see ). Topic interactions are: discovery, create, read configuration, update configuration, and delete configuration. These operations concern the management of the topics. The topic-data interactions are: publish, subscribe, unsubscribe, and read. These operations are oriented on how data is transferred from a publisher to a subscriber.

Managing Topics shows the resources related to a topic collection that can be managed at the broker.

Resources of a Broker

The broker exports one or more topic collection resources, with resource type "core.ps.coll" defined in of this document. The interface for the topic collection resource is defined in . A topic collection resource can have topic resources as its child resources, with resource type "core.ps.conf". Other child resource types are currently not defined for a topic collection resource.

PubSub Topics The broker hosts a collection of topics. These topics as well as the collection itself are exposed by a CoAP server as resources (see ). Each topic contains a set of properties for configuration, one of which is the URI of the topic-data resource. The topic resource is used by a client for creating or administering a topic. The topic-data resource is used by the publishers and the subscribers to share the data values.

Topic and topic-data resources of a topic

Collection Representation Each topic is represented as a link, where the link target is the URI of the corresponding topic resource. Publication and subscription to a topic occur at the target of a link, which is the URI of the corresponding topic-data resource. Such a link is specified by the "topic-data" topic property within the topic resource (see ). A topic resource can also be simply called "topic". The list of links to the topic resources can be retrieved from the associated topic collection resource, represented as a CoRE Link Format document where each link targets a topic resource of type "core.ps.conf" as defined in this document.

Topic Representation A CoAP client can create a new topic by submitting an initial configuration for the topic (see ). It can also read and update the configuration of existing topics and topic properties as well as delete them when they are no longer needed (see ). The configuration of a topic itself consists of a set of topic properties that can be set by a client or by the broker. The topic is represented as a CBOR map containing the topic properties as top-level elements. The topic properties defined in this document are listed in , with their CBOR abbreviations in . Further topic properties can be registered in the registry established in .

Topic Properties The CBOR map includes the following topic properties, whose CBOR abbreviations are defined in .

• "topic-name": A required field used as an application identifier. It encodes the topic name as a CBOR text string. Examples of topic names include human-readable strings (e.g., "room2"), UUIDs, or other values. The "topic-name" is required at topic creation to enable the broker to detect duplicate creation requests and to provide a stable application-level identifier. Applications that do not require human-readable names MAY use automatically generated values such as UUIDs.
• "topic-data": A required field (optional during creation) containing the URI of the topic-data resource for publishing/subscribing to this topic. It encodes the URI reference as a CBOR text string. The topic-data resource is controlled by the broker but may be served from a different address than the topic resource. Clients MUST use the URI in this field to reach the topic-data resource. Clients MUST NOT derive that URI from the URI of the topic resource. If a URI is not provided when creating the topic, the choice of the URI for the topic-data resource is left to the broker.
• "resource-type": A required field used to indicate the resource type of the topic-data resource for the topic. It encodes the resource type as a CBOR text string. This document defines the value "core.ps.data". Other specifications or deployments MAY define and use alternative resource type values for the topic-data resource.
• "topic-content-format": This optional field specifies the canonical CoAP Content-Format identifier of the topic-data resource representation as an unsigned integer, e.g., 60 for the media-type "application/cbor".
• "topic-type": An optional field used to indicate the attribute or property of the topic-data resource for the topic. It encodes the attribute as a CBOR text string. Example attributes include "temperature".
• "expiration-date": An optional field used to indicate the expiration date of the topic. It encodes the expiration date as a CBOR tag 1 (epoch-based date/time) as defined in Section of RFC 8949 , representing the number of seconds since 1970-01-01T00:00Z in UTC time. If this field is not present, the topic will not expire automatically. When "expiration-date" is reached, the topic resource is deleted as described in .
• "max-subscribers": An optional field used to indicate the maximum number of simultaneous subscribers allowed for the topic. It encodes the maximum number as a CBOR unsigned integer. If this field is not present, the topic configuration sets no limit. A broker MAY still enforce its own limit, e.g., based on its available resources, without exposing it in this field. At topic creation or update, this field is a hint from the topic creator; the broker MAY store a different value than the one requested, or none at all. Once stored, the value is enforced: if the limit is reached, new subscriptions are handled as specified in .
• "observer-check": An optional field that controls the maximum number of seconds between two consecutive Observe notifications sent as Confirmable messages to each topic subscriber (see ). It is encoded as a CBOR unsigned integer greater than 0 and no greater than 86400, since requires a Confirmable notification at least every 24 hours. It ensures that subscribers that have lost interest and silently forgotten the observation do not remain indefinitely on the server's observer list. At topic creation or update, this field is a hint from the topic creator; the broker MAY store a different value than the one requested, within the same bound. Once stored, the server hosting the topic-data resource applies the value. The default value for this field is 86400, which corresponds to 24 hours.

A broker MUST ignore topic properties that it does not recognize. Ignored properties are not stored and do not appear in the representation of the topic resource. Since the responses to topic creation and update return the current representation of the topic resource (see , , and ), a client can determine from the response which of the properties it sent were accepted. The "resource-type" field carries a single value pertaining to the publish-subscribe functionality of the topic-data resource. The topic-data resource itself MAY have additional resource types visible in Link-Format discovery , but those are not represented in this field.

Discovery A client can perform a discovery of: the broker; the topic collection resources and topic resources hosted by the broker; and the topic-data resources associated with those topic resources. Any server implementing a pubsub broker MUST support CoAP discovery with a query parameter as defined in and as used in the examples in this section. The CoRE Link Format discovery responses shown in the examples in this section are illustrative only. The normative requirements for this format are defined in . The examples make minimal use of CoRE Link Format attributes, in order to reduce the size of discovery responses: this is beneficial for clients connected to constrained networks. In general, a broker MAY include any CoRE Link Format attributes in each returned link, for example to meet specific use case requirements.

Broker Discovery CoAP clients can discover brokers by using CoAP discovery , via multicast, through a Resource Directory (RD) or by other means specified in extensions to . Brokers can register with an RD by following the steps in with the resource type set to "core.ps" as defined in of this document. The following example shows an endpoint discovering a broker using the "core.ps" resource type over a multicast network. Brokers within the multicast scope will answer the query. Even when that discovery is unprotected, it does not disclose the existence of the topics but only that of the broker. ;rt="core.ps" ]]>

Topic Collection Discovery The topic collection resource is the entry point for topic discovery, since its representation lists the topics it contains (see ). A broker SHOULD make its topic collection resources discoverable via "/.well-known/core" (see ), identified by the resource type "core.ps.coll". A broker that restricts the discovery of its topic collections to authorized clients can omit them from "/.well-known/core" and rely on other means, such as a Resource Directory or pre-configuration. The specific resource path is left for implementations. Examples in this document use the "/ps" path. The interactions with a topic collection are further defined in . Since the representation of the topic collection resource includes the links to the associated topic resources, it is not required to locate those links under "/.well-known/core", also in order to limit the size of the CoRE Link Format document returned as result of the discovery. Example: ;rt="core.ps.coll", ;rt="core.ps.coll" ]]> Note that in this example the "ct" attribute is not included for the two collections in the returned CoRE Link Format document. This is because the "ct" attribute is an optional hint, which is not needed in this case: the Content-Format of each topic collection resource is implied by its resource type (rt="core.ps.coll") to be 40 ("application/link-format").

Topic Discovery A broker can also list its topic resources in /.well-known/core, identified by the resource type "core.ps.conf". Each topic collection is associated with a group of topic resources, each detailing the configuration of its respective topic (refer to ). Below is an example of discovery via /.well-known/core with query rt=core.ps.conf that returns a list of topics, as the list of links to the corresponding topic resources. ;rt="core.ps.conf", ;rt="core.ps.conf" ]]> In certain scenarios, the method described herein may not be applicable, e.g., if the server wants to restrict topic availability. For example, the server hosting /.well-known/core may not be aware of the broker's authorization policy, the discovery interaction may need to be secured, or the size of the returned CoRE Link Format document may grow large. While allows per-entry access control in /.well-known/core, in such cases it is recommended to utilize the procedure outlined in and for topic discovery instead.

Topic-Data Discovery The "topic-data" topic property of a topic contains the URI of the topic-data resource used for publishing and subscribing. Retrieving the topic will also provide the URL of the topic-data resource (see ). This specification defines the resource type "core.ps.data" for topic-data resources. Other specifications or deployments MAY use alternative resource type values (see ). It is also possible to discover a list of topic-data resources by sending a request to the collection resource with a query parameter rt=core.ps.data, as shown in the example below. Every topic collection resource MUST support this query. ]]> Note that the "rt" attribute is not included in the returned link in the example response. This is because the query in the request already constrains all links in the response to be only of type "core.ps.data". Therefore, including the "rt" attribute for each returned link would be unnecessary and would make the response size much larger. A broker MAY elide these attributes to minimize the size of discovery response payloads, as the broker in this example does.

Topic Collection Interactions A broker MUST support all the interactions with a topic collection resource defined in this section. A client MAY use any subset of them. The CoRE Link Format responses shown in the examples in this section are illustrative only. The normative requirements for this format are defined in . The examples make minimal use of CoRE Link Format attributes, in order to reduce the size of responses: this is beneficial for clients connected to constrained networks. In general, a broker MAY include any CoRE Link Format attributes in each returned link, for example to meet specific use case requirements.

Retrieving all topics A client can request a collection of the topics present in the broker by making a GET request to the topic collection URI. On success, the broker returns a successful response (typically 2.05 Content), specifying the list of links to topic resources associated with this topic collection (see ). The broker MAY limit the returned list to the topics that the client is authorized to access. Discovery of the topic collection resource itself is described in . The Content-Format 40 ("application/link-format") MUST be supported for the topic collection resource. Example: , ]]> Note that no "rt" or "ct" attributes are returned for the topic resources in the example payload, because the resource type (rt="core.ps.conf") is already implied by this specification for the topic collection and the content-format (TBD606) is implied by the resource type.

Getting Topics by Topic Properties A client can filter a collection of topics by submitting the representation of a topic filter (see ) in a FETCH request to the topic collection URI. On success, the broker returns a successful response (typically 2.05 Content) with a representation of a list of topics in the collection (see ) that match the filter in CoRE Link Format . Upon success, the broker responds with a successful response (typically 2.05 Content), providing a list of links to topic resources associated with this topic collection that match the request's filter criteria (refer to ). A positive match happens only when each topic property in the request payload is present with the indicated value in the topic resource representation. This section describes FETCH semantics on the topic collection for request payloads with Content-Format TBD606 ("application/core-pubsub+cbor"), for which the response uses Content-Format 40 ("application/link-format"). Extensions that define other request Content-Formats also define the Content-Format of the corresponding response. Example: ]]> Note that in this example no "rt" or "ct" attributes are returned in the response payload, since the type of each link (topic resource with rt="core.ps.conf") is implied as the default resource type of each topic resource by this specification. Eliding these attributes helps to minimize the size of the response payload.

Creating a Topic A client can add a new topic to a collection of topics by submitting an initial representation of the topic resource (see ) in a POST request to the topic collection URI. The request MUST include the "topic-name" and "resource-type" topic properties, and MAY include any other topic property in . On success, the broker returns a 2.01 (Created) response, indicating the Location-Path of the new topic and the current representation of the topic resource. The response payload is a CBOR map. The response MUST include the required topic properties "topic-name", "resource-type", and "topic-data" (see ), and MAY include optional topic properties. The response MUST support Content-Format TBD606 ("application/core-pubsub+cbor"), which is the default. If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST reply with a 4.xx client error response (such as 4.03 Forbidden). The broker MUST reply with a 4.xx client error response (such as 4.00 Bad Request) if the value of a recognized topic property is invalid, or if the "topic-name" is already in use or otherwise invalid. Unrecognized topic properties are ignored (see ). If the request includes a "topic-data" URI at which the broker cannot serve the topic-data resource, the broker MUST reply with a 4.xx client error response (such as 4.00 Bad Request). Below is an example of a successful topic creation:

Topic Interactions A broker MUST support all the interactions with a topic resource defined in this section. A client MAY use any subset of them.

Getting a topic A client can read the configuration of a topic by making a GET request to the topic resource URI. On success, the broker returns a successful response (typically 2.05 Content) with a representation of the topic resource, as specified in . If requirements are defined for the client to read the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST reply with a 4.xx client error response (such as 4.03 Forbidden). The response payload is a CBOR map, whose possible entries are specified in and use the same abbreviations defined in . Successful responses to GET and FETCH requests on a topic resource are cacheable, following and . The broker uses the Max-Age option to indicate for how long a topic representation can be considered fresh, taking into account that the topic configuration can be updated or the topic deleted at any time. For example, below is a request on the topic "/ps/h9392":

Getting part of a topic A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific topic properties. This is done in order to retrieve part of the current topic resource. The request payload is a CBOR array of topic property keys, using the same abbreviations defined in , and is carried with Content-Format 60 ("application/cbor"). Each element of the array specifies one requested topic property of the current topic resource (see ). On success, the broker returns a successful response (typically 2.05 Content) with a representation of the topic resource. The response has as payload the partial representation of the topic resource as specified in . If requirements are defined for the client to read the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST reply with a 4.xx client error response (such as 4.03 Forbidden). The response payload is a CBOR map, whose possible entries are specified in and use the same abbreviations defined in . Content-Format 60 ("application/cbor") is mandatory to support for the request payload, and Content-Format TBD606 ("application/core-pubsub+cbor") is mandatory to support for the response payload. The CBOR map in the response payload includes entries for each topic property specified in the request and available in the topic resource representation. Example:

Updating the topic A client can update a topic's configuration by submitting the updated topic representation in a POST request to the topic URI. However, the topic properties "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker. Since POST replaces the full resource representation, these immutable properties may be included in the request with their current values. On success, the topic is overwritten and the broker returns a 2.04 (Changed) response and the current full resource representation. Decreasing "max-subscribers" causes some subscribers to be unsubscribed. Unsubscribed endpoints receive a final 4.04 (Not Found) response as per . The specific queue management for unsubscribing is left for implementors. Please note that when using POST the topic is being overwritten, thus any optional topic property (e.g., "max-subscribers", "observer-check") not included in the POST message is reset to its default value. Example: Note that, when a topic changes through either update method (POST or iPATCH), it may result in disruptions for the subscribers. Some potential issues that may arise include:

• Reducing the number of subscribers will cause cancellation of ongoing subscriptions if the new "max-subscribers" has been exceeded.
• Changing the "expiration-date" to an earlier time will cause the topic to expire earlier, cancelling ongoing subscriptions at that time.

Updating the topic with iPATCH A client can partially update a topic's configuration by submitting a partial topic representation in an iPATCH request to the topic URI. The request payload is a CBOR map with Content-Format TBD606 ("application/core-pubsub+cbor") carrying the topic properties to update. Each topic property present in the request replaces the current value of that property in the topic resource. Topic properties absent from the request are left unchanged. As with the POST method, the topic properties "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker. On success, the broker returns a 2.04 (Changed) response and the current full resource representation. The broker only updates topic properties that are explicitly mentioned in the request. The disruptions for subscribers described in apply to iPATCH updates as well. Contrary to POST, iPATCH operations will explicitly update some topic properties, leaving others unmodified. In the below example, two properties are successfully updated with iPATCH:

Deleting a topic A client can delete a topic by making a CoAP DELETE request on the topic resource URI. On success, the broker returns a 2.02 (Deleted) response. Since CoAP DELETE is idempotent, a client retransmitting a DELETE request for an already-deleted topic may receive a 4.04 (Not Found) response, which can be considered a successful deletion. When a topic resource is deleted, the broker MUST also delete the topic-data resource. As a result, all observers of the topic-data resource are removed from the list of observers and receive a final 4.04 (Not Found) response as per . Example:

Publish and Subscribe The overview of the publish-subscribe mechanism based on CoAP is as follows: a publisher publishes to a topic by submitting the data in a PUT request to a topic-data resource and subscribers subscribe to a topic by submitting a GET request with the Observe option set to 0 (register) to a topic-data resource. When resource state changes, the server will send a notification to current subscribers observing the resource . The broker creates the topic-data resource when it creates the topic. Until a publisher has published to it, the topic-data resource exists but has no representation: a GET request on it returns 2.06 (No Content) , and a subscriber can register for notifications and receives the first publication as a notification (see ). URIs for topic resources are broker-generated (see ). Clients obtain the URI of the topic-data resource from the "topic-data" property (see ); it has no necessary URI pattern dependence on the URI of the topic resource.

Topic Lifecycle When a topic is created, the broker places it in the CREATED state (see ) and creates its topic-data resource. In this state a client can read, update and delete the topic, a publisher can publish to the topic-data resource, and a subscriber can read or observe the topic-data resource. Until the first publication, the topic-data resource has no representation: a GET request on it returns 2.06 (No Content), an Observe registration is confirmed with 2.06 (No Content), and observers receive a 2.05 (Content) notification when the first representation is published .

Lifecycle of a Topic | CREATED +--------------->| DELETED | | | Delete topic | | '-------------' '-------------' ]]>

When a client deletes a topic resource, the topic is placed into the DELETED state and shortly after removed from the server. Both the topic resource and the topic-data resource are deleted. All observers of the topic-data resource are removed from the list of observers with a final 4.04 (Not Found) response as per , and no further interactions with the topic are possible.

Topic-Data Interactions The server hosting the topic-data resource MUST support all the interactions defined in this section and in . A client MAY use any subset of them.

Publish A topic must have been created (see ) in order to publish data to its topic-data resource. A client can publish data to a topic by submitting the data in a PUT request to the topic-data resource. The URI for this resource is indicated in the "topic-data" topic property value. Please note that this URI is not the same as the topic URI used for configuring the topic (see ). On success, the server returns a successful response, typically 2.04 (Changed). The first publication to a topic-data resource that has no representation is handled like any other publication. If the request does not have an acceptable Content-Format, e.g., as specified by the "topic-content-format" property in the topic configuration, the server returns a 4.15 (Unsupported Content-Format) response. If the client is sending publications too fast, the server returns a 4.29 (Too Many Requests) response . Example of a publication:

Subscribe A client can subscribe to a topic-data resource by sending a CoAP GET request with the CoAP Observe Option set to 0 to subscribe to resource updates . On success, the server hosting the topic-data resource returns a successful response (typically 2.05 Content) with the data and the Observe Option. If no Observe Option is present in the response, the client should assume that the subscription was not successful. If the topic-data resource has no representation yet, the server confirms the registration with a 2.06 (No Content) response carrying the Observe Option , and the subscriber receives the first publication as a 2.05 (Content) notification. Since a 2.06 (No Content) response carries no Content-Format, a subscriber that needs a specific Content-Format SHOULD include the Accept Option in the registration request; the "topic-content-format" property, when present, indicates the Content-Format to request. The following response codes are defined for the Subscribe operation:

Success:

2.05 (Content). The current topic data is included in the response. In case of successful subscription, the response includes the Observe Option.

Success:

2.06 (No Content). The topic-data resource exists and has no representation yet. In case of successful subscription, the response includes the Observe Option.

Failure:

4.04 (Not Found). The topic does not exist.

If the "max-subscribers" topic property value has been reached, the server must treat that as specified in . The 2.05 (Content) or 2.06 (No Content) response MUST NOT include an Observe Option, the absence of which signals to the subscriber that the subscription failed. Example of a subscription before the first publication, followed by the notification of that publication: Example of a subscription to a topic with data, followed by one update:

Unsubscribe A CoAP client can unsubscribe by canceling the observation as described in . For example, the client can use CoAP GET with the Observe Option set to 1 (deregister), or simply "forget" the observation and let the server remove it through its own observation lifetime mechanisms. As per , a server transmits notifications mostly as Non-confirmable messages, but it sends a notification as a Confirmable message instead of a Non-confirmable message at least every 24 hours. This value can be modified at the broker by the administrator of a topic by modifying the topic property "observer-check" (see ). This would allow changing the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource.

Read the latest data A client can get the latest published topic-data resource by making a GET request to the "topic-data" URI. Discovery of that URI through the "topic-data" topic property is described in . On success, the server returns a successful response (typically 2.05 Content) with the data. If the topic-data resource has no representation, the server returns 2.06 (No Content) . If the target URI does not match an existing resource, the server returns an error response (typically 4.04 Not Found). Example: This document only defines a mechanism for subscribers to retrieve the latest topic-data resource representation. For example, a future specification could enable subscribers to retrieve earlier representations of the topic-data resource, and could define additional topic properties, registered as described in , to control how many of them the broker stores.

Rate Limiting The server hosting the topic-data resource may have to handle a large number of publishers and subscribers at the same time. This means it could become overwhelmed if it receives too many publications in a short period of time. If a publisher is sending publications too fast, the server SHOULD return a 4.29 (Too Many Requests) response . As described in , the Max-Age option in this response indicates the number of seconds after which the client may retry. The server MAY also stop dispatching messages from that publisher for the indicated time. When a publisher receives a 4.29 (Too Many Requests) response, it MUST NOT send any new publication requests to the same topic-data resource before the time indicated by the Max-Age option has passed.

Encoding of PubSub Topic Properties This document defines topic properties used in the messages exchanged between a client and the broker, for example during the topic creation and configuration process (see ). summarizes them and specifies the CBOR key that MUST be used instead of the full descriptive name. Note that the media type "application/core-pubsub+cbor" MUST be used when these topic properties are transported in the respective CoAP message payloads. CoAP Pubsub Topic Properties and CBOR Encoding

Name	CBOR Key	CBOR Type
topic-name	0	tstr
topic-data	1	tstr
resource-type	2	tstr
topic-content-format	3	uint
topic-type	4	tstr
expiration-date	5	#6.1(number)
max-subscribers	6	uint
observer-check	7	uint

Security Considerations The architecture presented in this document inherits the security considerations from CoAP and Observe , as well as from Web Linking , CoRE Link Format , and the CoRE Resource Directory . CoAP communications between each client and the broker MUST be secured. The default security protocol is defined by . Examples of other security protocols that could be applied to CoAP communications are OSCORE and DTLS 1.3 . Protection MAY instead be provided below CoAP, e.g., by a secured link layer or by IPsec, as discussed for the NoSec mode in . The choice of a security protocol depends on the requirements of the specific application and deployment. Security considerations for the selected security protocol apply as well. The content published on a topic by a publisher client SHOULD be protected end-to-end between the publisher and all the subscribers to that topic. Such protection MUST include source authentication of the published data, so that subscribers can verify its origin. This can be achieved at the application layer, e.g., by using COSE . A 2.06 (No Content) response reveals that a topic-data resource exists. A broker that enforces access control on topic-data resources responds to unauthorized clients as it would for a nonexistent resource (see ). Access control of clients at the broker MAY be enforced for performing discovery operations, and SHOULD be enforced in a fine-grained fashion for operations related to the creation, update, and deletion of topic resources, as well as for operations on topic-data resources such as publication on and subscription to topics. This prevents rogue clients to, among other things, repeatedly create topics at the broker or publish (large) contents, which may result in Denial of Service against the broker and the active subscribers. The application profile for publish-subscribe communication with CoAP , which builds on , provides a security model that can be used in the architecture presented in this document, in order to enable secure communication between the different parties as well as secure, authorized operations of publishers and subscribers that fulfill the requirements above. In particular, the application profile above relies on the ACE framework and defines a method to:

• authorize publishers and subscribers to perform operations at the broker, with fine-grained access control;
• authorize publishers and subscribers to obtain the keying material required to take part to a topic managed by the broker that also hosts the corresponding topic-data resource;
• protect published data end-to-end between a publisher and all the subscribers to the targeted topic, ensuring confidentiality, integrity, and source authentication of the published content.

That approach can be extended to enforce authorization and fine-grained access control for administrator clients that are intended to create, update, and delete topics at the broker.

IANA Considerations This document has the following actions for IANA. Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification and delete this paragraph.

Media Type Registrations This specification registers the "application/core-pubsub+cbor" media type in the IANA Media Types registry. It is used for messages of the protocols defined in this document and carries topic properties encoded in CBOR. In an iPATCH request to a topic resource, the map carries the topic properties to update (see ). This registration follows the procedures specified in .

Type name:

application

Subtype name:

core-pubsub+cbor

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

Must be encoded as a CBOR map containing the topic properties defined in [RFC-XXXX].

Security considerations:

See of [RFC-XXXX].

Interoperability considerations:

none

Published specification:

[RFC-XXXX]

Applications that use this media type:

This type is used by clients that create, retrieve, and update topics at servers acting as a broker.

Fragment identifier considerations:

N/A

Additional information:

N/A

Person & email address to contact for further information:

CoRE WG mailing list (core@ietf.org), or IETF Web and Internet Transport (WIT) Area (wit@ietf.org)

Intended usage:

COMMON

Restrictions on usage:

none

Author/Change controller:

IETF

Provisional registration:

no

CoAP Content-Formats IANA is asked to register the following entry to the "CoAP Content-Formats" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group.

Content Type:

application/core-pubsub+cbor

Content Coding:

-

ID:

TBD606

Reference:

[RFC-XXXX]

Resource Types IANA is asked to enter the following values from in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained Restful Environments (CoRE) Parameters" registry group. Reference should always be [RFC-XXXX]. CoAP Pubsub Resource Types

Value	Description
core.ps	Publish-subscribe broker
core.ps.coll	Topic collection resource of a publish-subscribe broker
core.ps.conf	Topic resource of a publish-subscribe broker
core.ps.data	Topic-data resource of a publish-subscribe server

CoAP Pubsub Topic Properties Registry This specification establishes the "CoAP Pubsub Topic Properties" IANA registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group. The registration policy is either "Private Use", "Standards Action with Expert Review", "Specification Required", or "Expert Review" per . "Expert Review" guidelines are provided in . All assignments according to "Standards Action with Expert Review" are made on a "Standards Action" basis per Section of RFC 8126 with "Expert Review" additionally required per Section of RFC 8126 . The procedure for early IANA allocation of "standards track code points" defined in also applies. When such a procedure is used, IANA will ask the designated expert(s) to approve the early allocation before registration. In addition, working group chairs are encouraged to consult the expert(s) early during the process outlined in Section of RFC 7120 . The columns of this registry are:

• Name: This is a descriptive name that enables easier reference to the item. The name MUST be unique. It is not used in the encoding.
• CBOR Key: This is the value used as the CBOR key of the item. These values MUST be unique. The value is an integer (either positive or negative). Different ranges of values use different registration policies . Integer values from -256 to 255 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535 are designated as "Specification Required". Integer values greater than 65535 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use".
• CBOR Type: This contains the CBOR type of the item, or a pointer to the registry that defines its type, when that depends on another item.
• Reference: This contains a pointer to the public specification for the item.

This registry has been initially populated with the values in . For all of them, the reference is [RFC-XXXX].

Expert Review Instructions The registration policy for the IANA registry established in is defined as one of "Standards Action with Expert Review", "Specification Required", and "Expert Review". This section gives some general guidelines for what the experts should be looking for; however, they are being designated as experts for a reason, so they should be given substantial latitude. These registration policies are designed to accommodate different use cases; "Standards Action with Expert Review" allows for further IETF standards and extensions, maintaining consistency and alignment with established protocols; "Specification Required" allows third-party specifications from Standards Development Organizations (SDOs) to register topic properties, enabling interoperability and broader applicability; and "Expert Review" provides a flexible mechanism for exposing new properties that implementors do not want to keep in a private range. Expert reviewers should take into consideration the following points:

• Clarity and correctness of registrations. Experts are expected to check the clarity of purpose and use of the requested entries. Experts need to make sure that registered topic properties are clearly defined in the corresponding specification. Properties that do not meet these objectives of clarity and completeness must not be registered.
• Code point squatting should be discouraged. Reviewers are encouraged to get sufficient information for registration requests to ensure that the usage is not going to duplicate one that is already registered and that the code point is likely to be used in deployments. The zones tagged as "Private Use" are intended for testing purposes and closed environments. Code points in other ranges should not be assigned for testing.
• Specifications are required for the "Standards Action With Expert Review" range of code point assignment. Specifications should exist for "Specification Required" ranges, but early assignment before a specification is available is considered to be permissible. When specifications are not provided, the description provided needs to have sufficient information to identify what the code point is being used for.
• Experts should take into account the expected usage of fields when approving a code point assignment. Documents published via Standards Action can also register code points outside the Standards Action range. The length of the encoded value should be weighed against how many code points of that length are left, the size of device it will be used on, and the number of code points left that encode to that size.

References Normative References 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 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. 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. Ericsson Universität Bremen TZI This specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). It also defines the serialisation of such links in HTTP headers with the Link header field. A Constrained Application Protocol (CoAP) server can experience temporary overload because one or more clients are sending requests to the server at a higher rate than the server is capable or willing to handle. This document defines a new CoAP response code for a server to indicate that a client should reduce the rate of requests. 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. 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 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. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. This document specifies IANA registration procedures for MIME external body access types and content-transfer-encodings. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. This document defines best practices for defining new top-level media types. It also introduces a registry for top-level media types, and contains a short history of top-level media types. It updates RFC 6838. This memo describes the process for early allocation of code points by IANA from registries for which "Specification Required", "RFC Required", "IETF Review", or "Standards Action" policies apply. This process can be used to alleviate the problem where code point allocation is needed to facilitate desired or required implementation and deployment experience prior to publication of an RFC, which would normally trigger code point allocation. The procedures in this document are intended to apply only to IETF Stream documents. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This document defines Object Security for Constrained RESTful Environments (OSCORE), a method for application-layer protection of the Constrained Application Protocol (CoAP), using CBOR Object Signing and Encryption (COSE). OSCORE provides end-to-end protection between endpoints communicating using CoAP or CoAP-mappable HTTP. OSCORE is designed for constrained nodes and networks supporting a range of proxy operations, including translation between different transport protocols. Although an optional functionality of CoAP, OSCORE alters CoAP options processing and IANA registration. Therefore, this document updates RFC 7252. Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. This document, along with RFC 9053, obsoletes RFC 8152. Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. CBOR Object Signing and Encryption (COSE) defines a set of security services for CBOR. This document defines a countersignature algorithm along with the needed header parameters and CBOR tags for COSE. This document updates RFC 9052. This document specifies version 1.3 of the Datagram Transport Layer Security (DTLS) protocol. DTLS 1.3 allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection / non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol. This document obsoletes RFC 6347. Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines a set of algorithms that can be used with the CBOR Object Signing and Encryption (COSE) protocol (RFC 9052). This document, along with RFC 9052, obsoletes RFC 8152. 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 defines how to use the Authentication and Authorization for Constrained Environments (ACE) framework to distribute keying material and configuration parameters for secure group communication. Candidate group members that act as Clients and are authorized to join a group can do so by interacting with a Key Distribution Center (KDC) acting as the Resource Server, from which they obtain the keying material to communicate with other group members. While defining general message formats as well as the interface and operations available at the KDC, this document supports different approaches and protocols for secure group communication. Therefore, details are delegated to separate application profiles of this document as specialized instances that target a particular group communication approach and define how communications in the group are protected. Compliance requirements for such application profiles are also specified. Ericsson This document explores how the Constrained RESTful Application Language (CoRAL) might be used for enabling publish/subscribe-style communication over the Constrained Application Protocol (CoAP), which allows CoAP nodes with long breaks in connectivity and/or up-time to exchange data via a publish/subscribe broker. RISE AB RISE AB Ericsson AB Group communication for the Constrained Application Protocol (CoAP) can be secured using Group Object Security for Constrained RESTful Environments (Group OSCORE). A Group Manager is responsible for handling the joining of new group members, as well as for managing and distributing the group keying material. This document defines a RESTful admin interface at the Group Manager that allows an Administrator entity to create and delete OSCORE groups, as well as to retrieve and update their configuration. The Authentication and Authorization for Constrained Environments (ACE) framework is used to enforce authentication and authorization of the Administrator at the Group Manager. Protocol-specific transport profiles of ACE are used to achieve communication security, proof of possession, and server authentication. Ericsson Brunel University RISE AB This document defines an application profile of the Authentication and Authorization for Constrained Environments (ACE) framework, to enable secure group communication in the Publish-Subscribe (Pub-Sub) architecture for the Constrained Application Protocol (CoAP) [draft- ietf-core-coap-pubsub], where Publishers and Subscribers communicate through a Broker. This profile relies on protocol-specific transport profiles of ACE to achieve communication security, server authentication, and proof-of-possession for a key owned by the Client and bound to an OAuth 2.0 access token. This document specifies the provisioning and enforcement of authorization information for Clients to act as Publishers and/or Subscribers, as well as the provisioning of keying material and security parameters that Clients use for protecting their communications end-to-end through the Broker. Note to RFC Editor: Please replace "[draft-ietf-core-coap-pubsub]" with the RFC number of that document and delete this paragraph. ARM SmartThings Huawei Tampere University This document defines a set of Constrained RESTful Environments (CoRE) Link Format Interface Descriptions [RFC6690] applicable for use in constrained environments. These include the: Actuator, Parameter, Read-only parameter, Sensor, Batch, Linked Batch and Link List interfaces. The Batch, Linked Batch and Link List interfaces make use of resource collections. This document further describes how collections relate to interfaces. Many applications require a set of interface descriptions in order provide the required functionality. This document defines an Interface Description attribute value to describe resources conforming to a particular interface. Editor's notes: o The git repository for the draft is found at https://github.com/

Document Updates

Version -13 to -14

• Section restructuring for better readability.
• Updated topic configuration interactions.
• Introduced iPATCH section.
• Various clarifications of default values for parameters.
• New examples for several interactions.
• Updated topic discovery section.
• Other editorial changes

Version -14 to -15

• Code bug fix https://github.com/jaimejim/aiocoap-pubsub-broker/commit/f32ce4866a81319238d6e905de439c9410cce175
• Added two new optional topic configuration parameters; "initialize" and "topic-history".
• Modified all examples to conform to RFC9594.
• Added the explicit cancellation of ongoing subscriptions when topic configuration parameters are changed.
• Added editorial changes based on feedback.
• Clarifications on Topic Configuration creation.
• Other editorial changes

Version -15 to -16

• Various updates throughout the document based on AD review.
• IANA clarifications

Version -16 to -17

• Addressing Esko's and Ari's review.
• Fixing formatting

Version -17 to -18

• Addressed issues #64, #65, #66, #67.
• rt, ct, obs attribute elision
• Editorial changes

Version -18 to -19

• IANA early review
• Addressed issues #68, #69
• Addressed Marco's review
• Addressed Marco's and Christian Amsüss's WGLC reviews
• Redesigned "initialize" property for RFC7641 compliance
• Changed "expiration-date" to CBOR tag 1, CBOR keys numeric-only
• Relaxed overly strict response codes
• Clarified topic-data URI reference, immutable properties, and architecture roles
• Editorial fixes

Version -19 to -20

• Clarified "resource-type" field: "core.ps.data" per this specification, alternative values permitted
• Clarified "max-subscribers" semantics: hint at creation, enforced once stored
• Added explicit 4.04 removal of subscribers on topic-data deletion
• Merged PRs #71, #72, #73 (editorial fixes, aasvg build, example clarification)

Version -20 to -21

• Addressed remaining WGLC comments from the 2026-06-17 interim (PR #76)
• Added eventual-consistency semantics of pubsub messages
• Clarified "max-subscribers": broker may store a different value or none (PR #74)
• Removed unused RFC 6570 URI template reference (PR #77)
• IANA: named the Media Types registry, clarified "code point" (PR #78)
• Default security from RFC 7252; OSCORE and DTLS 1.3 kept informative (PR #79)
• Encoded the topic FETCH filter as an application/cbor array; removed conf-filter from the registry (PR #80)

Version -21 to -22 Addressed the AD review of -21:

• Topic-data resource is controlled by the broker and may be served from a different address; clients take its URI from the "topic-data" property
• Brokers support all interactions on topic collections, topics and topic-data; clients use any subset
• Reconciled topic collection discovery: GET on the collection always works, advertising it in /.well-known/core is a SHOULD
• Unrecognized topic properties are ignored; the returned representation shows which properties were accepted
• Defined the iPATCH request payload as the topic properties to update, in the text and in the media type registration
• Security between clients and broker is a MUST; protection below CoAP allowed as in RFC 7252 Section 9
• End-to-end protection, when used, includes source authentication
• "max-subscribers": the broker may enforce an undisclosed limit; "observer-check": bounded at 86400, hint until stored
• Replaced MAYs that granted no permission with "can" in broker and topic discovery; explicit MAY for eliding link attributes
• Link-format FETCH response tied to the TBD606 request Content-Format
• Topic resource GET and FETCH responses are cacheable; added RFC 8132 as a normative reference
• POST update resets any absent optional property; one subscriber-disruption note for both update methods
• Section 3.3 points to where the topic-data URI is discovered instead of calling it a required step
• Old-representations paragraph kept as an extensibility example
• Editorial nits; topic-data examples use Content-Format 112
• Replaced the HALF CREATED and FULLY CREATED states with one CREATED state: the broker creates the topic-data resource with the topic, GET and Observe on it return 2.06 (No Content) until the first publication; first publication returns 2.04; removed the "initialize" property; normative reference to draft-jimenez-core-coap-no-content
• Removed the Delete topic-data operation: a DELETE terminates all observations and therefore cannot clear a topic without losing its subscribers

Acknowledgements The current version of this document contains a substantial contribution by Klaus Hartke's proposal , which defines the topic resource model and structure as well as the topic lifecycle and interactions. The document follows a similar architectural design as that provided by Marco Tiloca's . The authors would like to thank , ,, , , , , , Peter van der Stok, Tim Kellogg, Anders Eriksson, , Mikko Majanen, , , Oscar Novo and Lorenzo Corneo for their valuable contributions and reviews. The authors also thank for his detailed AD review of -21.

Contributors RISE AB

Isafjordsgatan 22 Kista 164 40 Sweden marco.tiloca@ri.se

Marco offered comprehensive reviews and insightful guidance on the recent iterations of this document. His contributions were valuable in multiple parts of the document but particularly notable in the Security Considerations section.