CoAP Extensions for Asynchronous Task Resources
draft-li-coap-extensions-a2d-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
|---|---|---|---|
| Authors | Linzhe Li , Yong Cui | ||
| Last updated | 2026-06-17 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-li-coap-extensions-a2d-00
CORE Working Group L. Li
Internet-Draft Zhongguancun Laboratory
Intended status: Standards Track Y. Cui
Expires: 20 December 2026 Tsinghua University
18 June 2026
CoAP Extensions for Asynchronous Task Resources
draft-li-coap-extensions-a2d-00
Abstract
Many CoAP deployments need to start operations that cannot be
completed within one request/response exchange. Existing deployments
commonly model these operations with application-specific resources,
payload formats, and polling or notification conventions. This makes
clients, gateways, and proxies unable to interoperate across
implementations that expose otherwise similar long-running
operations.
This document defines a CoAP task-resource pattern for asynchronous
operations. It specifies a small set of CoAP Options and a CBOR
status representation that allow a server to create a temporary task
resource, allow a client to monitor, update, or cancel that task
using existing CoAP methods, and allow an Observe relationship to be
filtered in a predictable way. Autonomous control agents are one
motivating use case, but the mechanisms are intended to be generally
usable for constrained applications that need interoperable task
orchestration.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 20 December 2026.
Li & Cui Expires 20 December 2026 [Page 1]
Internet-Draft CoAP Task Resources June 2026
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Task Lifecycle . . . . . . . . . . . . . . . . . . . . . . . 5
5. CoAP Options . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. Expected-Effect Option . . . . . . . . . . . . . . . . . 6
5.2. Batch-Control Option . . . . . . . . . . . . . . . . . . 7
5.3. Observe-Filter Option . . . . . . . . . . . . . . . . . . 7
5.4. Progress-Link Option . . . . . . . . . . . . . . . . . . 8
6. Task-Resource Mapping . . . . . . . . . . . . . . . . . . . . 8
7. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . . . 8
8. Payload Formats . . . . . . . . . . . . . . . . . . . . . . . 9
8.1. Task Creation Payload . . . . . . . . . . . . . . . . . . 10
8.2. Task Status Payload . . . . . . . . . . . . . . . . . . . 10
9. Intermediary Considerations . . . . . . . . . . . . . . . . . 11
10. Security Considerations . . . . . . . . . . . . . . . . . . . 11
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
12.1. Normative References . . . . . . . . . . . . . . . . . . 12
12.2. Informative References . . . . . . . . . . . . . . . . . 13
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] provides a
RESTful interaction model for constrained nodes and constrained
networks. Many CoAP resources can be read or modified with a single
request and response. Other operations, however, are inherently
asynchronous: firmware installation, actuator motion, multi-resource
configuration, diagnostics, commissioning, and closed-loop automation
may continue after the initial request has been accepted.
Li & Cui Expires 20 December 2026 [Page 2]
Internet-Draft CoAP Task Resources June 2026
In current deployments, such long-running operations are often
represented in an application-specific manner. One server may return
a proprietary job URI in the payload, another may require repeated
polling of the original resource, and another may use Observe
[RFC7641] with implementation-specific state fields. These patterns
work within a single application profile, but they do not provide
common behavior for generic CoAP clients, gateways, cross-proxies,
management systems, or resource-constrained servers that need to
expose multiple kinds of long-running operations.
The lack of a common model creates several interoperability problems:
* A client has no standard way to discover the resource that
represents an accepted operation.
* A client has no common state vocabulary for deciding whether an
accepted operation is still pending, active, completed, failed,
aborted, or rejected.
* Gateways and intermediaries cannot recognize task-related traffic
without parsing application payloads.
* Observe notifications for progress or state changes can produce
excessive traffic when clients only need coarse progress updates
or minimum notification intervals.
* Multi-resource operations have no common request-level indication
of whether sub-operations are intended to be atomic, ordered, or
independently applied.
These are protocol interoperability issues rather than only
application design issues. They affect common CoAP behavior across
payload formats and deployment profiles. This document therefore
specifies a small CoAP extension for asynchronous task resources. It
preserves the CoAP REST model: task creation is performed with a
request to an application resource, the server returns an addressable
task resource, and the task is then monitored, modified, or canceled
with existing CoAP methods.
Autonomous AI agents provide a useful stress case for this work
because they can produce multi-step, non-instantaneous plans for
constrained devices. However, the wire image defined here is not
specific to AI. A conventional management client, scheduler, digital
twin, or automation controller can use the same task resource model.
Li & Cui Expires 20 December 2026 [Page 3]
Internet-Draft CoAP Task Resources June 2026
2. 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 BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Task: An asynchronous operation accepted by a CoAP server whose
execution continues after the initial request/response exchange.
Task Resource: A CoAP resource that represents one task instance.
It exposes the task state and may allow task update or
cancellation.
Task Initiator: A CoAP client that requests creation of a task. The
initiator can be a management client, automation controller,
scheduler, or autonomous agent.
Executor: A CoAP server that creates and executes a task resource.
Progress Link: A link from the response to the task resource that
was created for an accepted asynchronous operation.
Expected Effect: An optional assertion supplied by the task
initiator describing the intended effect of the operation. This
document defines only the CoAP option carriage; the semantics of
the assertion are application-profile specific.
3. Scope
This document specifies:
* the lifecycle of a CoAP task resource;
* CoAP Options that identify task-control behavior and provide a
link to a task resource;
* use of existing CoAP methods for monitoring, update, and
cancellation;
* an Observe filter option for reducing task-state notification
traffic; and
* a CBOR status representation for task resources.
Li & Cui Expires 20 December 2026 [Page 4]
Internet-Draft CoAP Task Resources June 2026
This document does not define a general intent language, a semantic
safety model, or an authorization framework for autonomous agents.
Those topics are expected to be handled by application profiles or by
other IETF work. This document also does not change the base CoAP
message layer, token processing, or retransmission behavior.
4. Task Lifecycle
A task resource represents an operation that has been accepted for
asynchronous processing. The task state is represented by the state
machine below.
+---------+ Rejection
| Pending | -------------------------> [ REJECTED ]
+---------+
|
| Accepted for execution
v
+---------+ Cancellation
| Active | -------------------------> [ ABORTED ]
+---------+
|
| Execution finishes
v
+--------------+
| Completed? | -- Yes ---------------> [ COMPLETED ]
+--------------+
|
| No
v
[ FAILED ]
Figure 1: Task Lifecycle
The state values are:
PENDING: The task has been received and a task resource exists, but
execution has not yet started.
ACTIVE: The task is executing.
COMPLETED: The task completed successfully.
FAILED: The task terminated without successful completion.
ABORTED: The task was canceled before completion.
REJECTED: The task was not accepted for execution, for example
Li & Cui Expires 20 December 2026 [Page 5]
Internet-Draft CoAP Task Resources June 2026
because of invalid parameters, conflicting state, missing
authorization, or a profile-specific safety policy.
An Executor SHOULD keep a terminal task resource available long
enough for the Task Initiator to retrieve the final state. The
retention time is deployment specific. After the retention time
expires, the server MAY remove the task resource and respond to later
requests with 4.04 (Not Found).
5. CoAP Options
This document defines the following CoAP Options. The option numbers
are temporary until IANA assignment.
+=================+======+=====+=====+===+========+========+
| Name | No. | C/E | U/N | R | Format | Length |
+=================+======+=====+=====+===+========+========+
| Expected-Effect | TBD1 | E | U | - | opaque | 0-1034 |
+-----------------+------+-----+-----+---+--------+--------+
| Batch-Control | TBD2 | E | U | - | uint | 0-2 |
+-----------------+------+-----+-----+---+--------+--------+
| Observe-Filter | TBD3 | E | U | - | opaque | 1-1034 |
+-----------------+------+-----+-----+---+--------+--------+
| Progress-Link | TBD4 | E | U | - | string | 1-255 |
+-----------------+------+-----+-----+---+--------+--------+
Table 1
The options are elective. A server that does not understand one of
these options processes the request according to normal CoAP option
processing. An application profile MAY define stricter behavior when
support for a specific option is required.
The options are marked unsafe-to-forward because they can affect
operation execution, notification generation, or interpretation of
the response. A proxy that does not understand these options MUST
follow the unsafe option processing rules in [RFC7252].
5.1. Expected-Effect Option
The Expected-Effect Option carries an application-profile-specific
assertion about the intended effect of a request. The option value
is opaque to the CoAP layer. Profiles MAY define the value as a CBOR
item, a constrained expression, or another compact representation.
If a server understands the option and the applicable application
profile, it MUST evaluate the assertion before transitioning the task
to ACTIVE. If the assertion is syntactically invalid for the
Li & Cui Expires 20 December 2026 [Page 6]
Internet-Draft CoAP Task Resources June 2026
profile, the server SHOULD respond with 4.00 (Bad Request). If the
assertion is valid but cannot be satisfied because of current
resource state or policy, the server SHOULD respond with 4.09
(Conflict) or create a task resource whose state is REJECTED.
The Expected-Effect Option is intended to make the expected outcome
visible at the protocol layer without requiring intermediaries to
parse the request payload. This document does not standardize the
assertion language.
5.2. Batch-Control Option
The Batch-Control Option indicates how sub-operations contained in
the request payload are intended to be executed. The option value is
a bit mask:
* 0x01 (Atomic): the server is requested to apply the sub-operations
as an atomic unit. If one sub-operation fails, the server rolls
back all sub-operations for which rollback is supported.
* 0x02 (Sequential): the server is requested to execute the sub-
operations in the order in which they appear in the payload.
If the server cannot provide the requested behavior, it MUST reject
the request with 4.00 (Bad Request) or 4.09 (Conflict), unless an
application profile defines different behavior. A server MUST NOT
silently treat an Atomic request as non-atomic.
5.3. Observe-Filter Option
The Observe-Filter Option is used with the Observe Option [RFC7641]
to reduce notification traffic. The option value is a CBOR map:
Observe-Filter = {
? 1 => uint, ; minimum notification interval in milliseconds
? 2 => uint, ; minimum progress delta in percentage points
}
When a server accepts an Observe registration that includes Observe-
Filter, it SHOULD suppress notifications that do not satisfy the
filter. A notification that reports a terminal state MUST NOT be
suppressed by the filter.
If the server does not support the supplied filter, it SHOULD reject
the Observe registration with 4.00 (Bad Request). If the Observe-
Filter Option is ignored because the server does not implement this
specification, normal elective option processing applies.
Li & Cui Expires 20 December 2026 [Page 7]
Internet-Draft CoAP Task Resources June 2026
5.4. Progress-Link Option
The Progress-Link Option is returned in a successful response when a
server has created a task resource for an accepted asynchronous
operation. The option value is a URI-reference encoded as a UTF-8
string. The value identifies the task resource.
A server SHOULD use Location-Path and Location-Query when they are
sufficient to identify the task resource. Progress-Link is useful
when a compact single option or an absolute URI-reference is needed
by a profile. If both Progress-Link and Location-Path/Location-Query
are present, they MUST identify the same task resource.
6. Task-Resource Mapping
To create a task, a Task Initiator sends a request to an application
resource. For example, a client can send a POST request to /actions/
climate or a FETCH or PATCH request [RFC8132] to a configuration
resource. If the Executor can complete the operation immediately, it
MAY return the final response directly. If the Executor accepts the
operation for asynchronous processing, it SHOULD return 2.02
(Accepted) and provide a link to the task resource.
The task resource is then controlled with existing CoAP methods:
GET: Retrieves the current task status. GET MAY be used with
Observe to receive task-state notifications.
FETCH: Retrieves selected task-state information when supported by
the task resource.
PATCH or iPATCH: Requests an update to mutable task parameters when
the task profile allows in-flight modification.
DELETE: Requests cancellation of the task. A successful
cancellation causes the task to transition to ABORTED. If the
task has already reached a terminal state, the server SHOULD
return the current terminal state or a response code appropriate
to the application profile.
The task resource URI is an implementation detail of the Executor.
Clients MUST NOT infer task semantics from the URI path alone.
7. Protocol Flow
The following example shows an asynchronous operation using a task
resource.
Li & Cui Expires 20 December 2026 [Page 8]
Internet-Draft CoAP Task Resources June 2026
Task Initiator Executor
| |
| POST /actions/climate |
| Content-Format: application/cbor |
| Expected-Effect: h'a1...' |
| Batch-Control: 0x03 |
|--------------------------------------->|
| | Validate request
| | Create /tasks/89
| |
| 2.02 Accepted |
| Location-Path: "tasks" |
| Location-Path: "89" |
| Progress-Link: "/tasks/89" |
|<---------------------------------------|
| |
| GET /tasks/89 |
| Observe: 0 |
| Observe-Filter: {1: 5000, 2: 20} |
|--------------------------------------->|
| |
| 2.05 Content |
| Observe: n |
| Payload: state=ACTIVE, progress=0 |
|<---------------------------------------|
| |
| 2.05 Content |
| Observe: n+1 |
| Payload: state=ACTIVE, progress=20 |
|<---------------------------------------|
| |
| PATCH /tasks/89 |
| Payload: update parameters |
|--------------------------------------->|
| |
| 2.04 Changed |
|<---------------------------------------|
| |
| 2.05 Content |
| Observe: n+2 |
| Payload: state=COMPLETED, progress=100|
|<---------------------------------------|
8. Payload Formats
Task resources SHOULD use CBOR [RFC8949] for compact status
representation. This document defines the following CDDL [RFC8610]
structures.
Li & Cui Expires 20 December 2026 [Page 9]
Internet-Draft CoAP Task Resources June 2026
8.1. Task Creation Payload
Application profiles define the payload used to create a task. When
a profile uses a generic multi-operation payload, it MAY use the
following structure:
Task-Request = {
? 1 => uint, ; client transaction identifier
2 => [ + Sub-Operation ]
}
Sub-Operation = {
1 => tstr, ; target sub-resource path
2 => uint / tstr / bstr ; target value or profile-defined value
}
8.2. Task Status Payload
The task resource status payload is:
Task-Status = {
1 => uint, ; task state
? 2 => uint, ; progress percentage, 0..100
? 3 => uint, ; estimated seconds to completion
? 4 => tstr, ; diagnostic text
? 5 => [ + Sub-Result ] ; per-sub-operation result
}
Sub-Result = {
1 => tstr, ; sub-resource path
2 => uint ; CoAP response code encoded as in RFC 7252
}
The task state values are:
Li & Cui Expires 20 December 2026 [Page 10]
Internet-Draft CoAP Task Resources June 2026
+=======+===========+
| Value | State |
+=======+===========+
| 0 | PENDING |
+-------+-----------+
| 1 | ACTIVE |
+-------+-----------+
| 2 | COMPLETED |
+-------+-----------+
| 3 | FAILED |
+-------+-----------+
| 4 | ABORTED |
+-------+-----------+
| 5 | REJECTED |
+-------+-----------+
Table 2
9. Intermediary Considerations
Intermediaries that understand this specification can recognize the
creation of task resources and the subsequent control traffic without
parsing application-specific payloads. This can be useful for
request routing, traffic prioritization, diagnostics, and policy
enforcement in constrained deployments.
Intermediaries MUST NOT change task-control options unless explicitly
configured to do so by the relevant application profile and security
policy. When OSCORE [RFC8613] protects an option end-to-end,
intermediaries cannot inspect or modify that option.
10. Security Considerations
Task resources can cause physical, operational, or management actions
to continue after the initial request has completed. Authorization
therefore needs to cover both task creation and subsequent operations
on the task resource. Deployments SHOULD use suitable CoAP security
mechanisms, such as DTLS, OSCORE [RFC8613], and ACE [RFC9200],
according to their threat model.
A Task Initiator that is authorized to create a task is not
necessarily authorized to observe, modify, or cancel all task
resources. Servers SHOULD apply authorization checks independently
to task creation, GET/Observe, PATCH, FETCH, and DELETE.
Observe-Filter can reduce notification traffic, but it can also hide
intermediate progress information from a client. Servers MUST NOT
suppress terminal-state notifications because of Observe-Filter.
Li & Cui Expires 20 December 2026 [Page 11]
Internet-Draft CoAP Task Resources June 2026
Expected-Effect can help a server or profile bind a request to an
asserted outcome. Because this document does not define the
assertion language, servers MUST treat the option according to the
application profile that defines that language. A server MUST NOT
assume that the mere presence of Expected-Effect is sufficient for
safety.
Task resources can reveal operational information, such as device
activity, failure causes, or expected completion time. Access to
task status therefore needs the same care as access to the underlying
application resource.
11. IANA Considerations
IANA is requested to allocate the following entries in the "CoAP
Option Numbers" registry:
+========+=================+===========+
| Number | Name | Reference |
+========+=================+===========+
| TBD1 | Expected-Effect | RFC-to-be |
+--------+-----------------+-----------+
| TBD2 | Batch-Control | RFC-to-be |
+--------+-----------------+-----------+
| TBD3 | Observe-Filter | RFC-to-be |
+--------+-----------------+-----------+
| TBD4 | Progress-Link | RFC-to-be |
+--------+-----------------+-----------+
Table 3
The option properties are defined in Section 5.
12. References
12.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/rfc/rfc7252>.
Li & Cui Expires 20 December 2026 [Page 12]
Internet-Draft CoAP Task Resources June 2026
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<https://www.rfc-editor.org/rfc/rfc7641>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/rfc/rfc8132>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/rfc/rfc8610>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/rfc/rfc8949>.
12.2. Informative References
[RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments
(OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019,
<https://www.rfc-editor.org/rfc/rfc8613>.
[RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for
Constrained Environments Using the OAuth 2.0 Framework
(ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022,
<https://www.rfc-editor.org/rfc/rfc9200>.
Acknowledgements
Thanks to Linbo Hui, Yannan Hu, Wenyong Wang, Shuisong Hu, Haoran
Luo, and Linzhe Li for their contribution to this draft.
Authors' Addresses
Li & Cui Expires 20 December 2026 [Page 13]
Internet-Draft CoAP Task Resources June 2026
Linzhe Li
Zhongguancun Laboratory
Beijing
100094
China
Email: lilz@zgclab.edu.cn
Yong Cui
Tsinghua University
Beijing, 100084
China
Email: cuiyong@tsinghua.edu.cn
URI: http://www.cuiyong.net/
Li & Cui Expires 20 December 2026 [Page 14]