idnits 2.17.1 draft-ietf-core-problem-details-01.txt: -(4): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (13 July 2020) is 1383 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-03 == Outdated reference: A later version (-15) exists of draft-ietf-core-href-03 -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group T. Fossati 3 Internet-Draft arm 4 Intended status: Standards Track J. Jiménez 5 Expires: 14 January 2021 K. Hartke 6 Ericsson 7 13 July 2020 9 Problem Details For CoAP APIs 10 draft-ietf-core-problem-details-01 12 Abstract 14 This document defines a "problem detail" as a way to carry machine- 15 readable details of errors in a CoAP response to avoid the need to 16 define new error response formats for CoAP APIs. The proposed format 17 is inspired by the Problem Details for HTTP APIs defined in RFC 7807. 19 Discussion Venues 21 This note is to be removed before publishing as an RFC. 23 Source for this draft and an issue tracker can be found at 24 https://github.com/core-wg/core-problem-details (https://github.com/ 25 core-wg/core-problem-details). 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 14 January 2021. 44 Copyright Notice 46 Copyright (c) 2020 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 62 2. Basic Problem Details . . . . . . . . . . . . . . . . . . . . 3 63 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. Additional Problem Details . . . . . . . . . . . . . . . . . 5 65 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 68 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 70 6.2. Informative References . . . . . . . . . . . . . . . . . 6 71 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 74 1. Introduction 76 CoAP [RFC7252] response codes are sometimes not sufficient to convey 77 enough information about an error to be helpful. This specification 78 defines a simple and extensible CoRAL [I-D.ietf-core-coral] 79 vocabulary to suit this purpose. It is designed to be reused by CoAP 80 APIs, which can identify distinct "problem types" specific to their 81 needs. Thus, API clients can be informed of both the high-level 82 error class (using the response code) and the finer-grained details 83 of the problem (using this vocabulary), as shown in Figure 1. 85 +--------+ +--------+ 86 | CoAP | | CoAP | 87 | Client | | Server | 88 +--------+ +--------+ 89 | | 90 | Request | 91 |----------------->| 92 | | 93 |<-----------------| 94 | Error Response | 95 | with a CoRAL | 96 | Document giving | 97 | Problem Details | 98 | | 100 Figure 1: Problem Details 102 The vocabulary presented is largely inspired by the Problem Details 103 for HTTP APIs defined in [RFC7807]. 105 1.1. Requirements Language 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in 110 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 111 capitals, as shown here. 113 2. Basic Problem Details 115 A CoAP Problem Details is a CoRAL document with the following 116 elements: 118 * "type" (id) - The problem type. This is a mandatory element. 120 * "title" (text) - A short, human-readable summary of the problem 121 type. It SHOULD NOT change from occurrence to occurrence of the 122 problem. 124 * "detail" (text) - A human-readable explanation specific to this 125 occurrence of the problem. 127 * "instance" (uri) - A URI reference that identifies the specific 128 occurrence of the problem. It may or may not yield further 129 information if dereferenced. 131 Consumers MUST use "type" as primary identifiers for the problem 132 type; the "title" string is advisory and included only for consumers 133 who are not aware of the semantics of the "type" value. 135 The "detail" member, if present, ought to focus on helping the client 136 correct the problem, rather than giving debugging information. 137 Consumers SHOULD NOT parse the "detail" member for information; 138 extensions (see Section 3) are more suitable and less error-prone 139 ways to obtain such information. 141 Note that the "instance" URI reference may be relative; this means 142 that it must be resolved relative to the document's base URI, as per 143 [I-D.ietf-core-coral]. 145 2.1. Examples 147 This section presents a series of examples of the basic vocabulary in 148 CoRAL textual format (Section 4 of [I-D.ietf-core-coral]). The 149 examples are fictitious. No identification with actual products is 150 intended or should be inferred. All examples involve the same CoAP 151 problem type with semantics of "unknown key id", defined in the 152 fictitious namespace "http://vocabulary.private-api.example". 154 Note that CoRAL documents are exchanged in CoRAL binary format 155 (Section 3 of [I-D.ietf-core-coral]) in practice. This includes the 156 use of [I-D.ietf-core-href] as an alternative to URIs that is 157 optimized for constrained nodes. 159 The example in Figure 2 has the most compact representation. It 160 avoids any non-mandatory element. This is suitable for a constrained 161 receiver that happens to have precise knowledge of the semantics 162 associated with the "type". 164 #using pd = 165 #using ex = 167 pd:type ex:unknown-key-id 169 Figure 2: Minimalist 171 The example in Figure 3 has all the mandatory as well as the optional 172 elements populated. This format is appropriate for a less 173 constrained receiver (for example, an edge gateway forwarding to a 174 log server that needs to gather as much contextual information as 175 possible, including the problem "headline", details about the error 176 condition, and an error-specific instance URL). 178 #using pd = 179 #using ex = 181 pd:type ex:unknown-key-id 182 pd:title "unknown key id" 183 pd:detail "Key with id 0x01020304 not registered" 184 pd:instance 186 Figure 3: Full-Fledged 188 3. Additional Problem Details 190 Problem type definitions MAY extend the Problem Details document with 191 additional elements to convey additional, problem-specific 192 information. 194 Clients consuming problem details MUST ignore any such elements that 195 they do not recognize; this allows problem types to evolve and 196 include additional information in the future. 198 3.1. Examples 200 The example in Figure 4 has all the basic elements as well as an 201 additional, type-specific element. 203 #using pd = 204 #using ex = 206 pd:type ex:unknown-key-id 207 pd:title "unknown key id" 208 pd:detail "Key with id 0x01020304 not registered" 209 pd:instance 210 ex:key-id 0x01020304 212 Figure 4: Full Payload and Extensions 214 4. Security Considerations 216 Problem Details for CoAP APIs are serialized in the CoRAL binary 217 format. See Section 11 of [RFC7252] for security considerations 218 relating to CoAP. See Section 7 of [I-D.ietf-core-coral] for 219 security considerations relating to CoRAL. 221 The security and privacy considerations outlined in Section 5 of 222 [RFC7807] apply in full. 224 5. IANA Considerations 226 TODO. 228 6. References 230 6.1. Normative References 232 [I-D.ietf-core-coral] 233 Hartke, K., "The Constrained RESTful Application Language 234 (CoRAL)", Work in Progress, Internet-Draft, draft-ietf- 235 core-coral-03, 9 March 2020, . 238 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 239 Requirement Levels", BCP 14, RFC 2119, 240 DOI 10.17487/RFC2119, March 1997, 241 . 243 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 244 Application Protocol (CoAP)", RFC 7252, 245 DOI 10.17487/RFC7252, June 2014, 246 . 248 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 249 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 250 May 2017, . 252 6.2. Informative References 254 [I-D.ietf-core-href] 255 Hartke, K., "Constrained Resource Identifiers", Work in 256 Progress, Internet-Draft, draft-ietf-core-href-03, 9 March 257 2020, . 260 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 261 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 262 . 264 Acknowledgments 266 Mark Nottingham and Erik Wilde, authors of RFC 7807. Carsten 267 Bormann, Jim Schaad, Christian Amsuess for review and comments on 268 this document. 270 Authors' Addresses 271 Thomas Fossati 272 arm 274 Email: thomas.fossati@arm.com 276 Jaime Jiménez 277 Ericsson 279 Email: jaime@iki.fi 281 Klaus Hartke 282 Ericsson 284 Email: klaus.hartke@ericsson.com