Concise Problem Details for Constrained Application Protocol (CoAP) APIs
draft-ietf-core-problem-details-08

# Problem-details write-up

Based on [8-02-22 Shepherd Writeup Template ](https://chairs.ietf.org/documents/qa-style-writeup-template)

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

The document has reached sufficient and broad agreement in the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

Before IESG evaluation, within the working group, there were no controversial parts. Two alternative proposals where presented (bundled and unbundled) and one was agreed upon.
After IESG evaluation, there was in-depth discussion about the appendix of the document, triggered by the ART ART/i18ndir review. That resulted in the removal of the CDDL in the appendix, and in some discussion about splitting the document between the main body and the appendix. After discussion and the addition of a clarifying paragraph about future updates to either part of the document, there was rough consensus to keep the document as is.

## Common Part

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

We are not aware of any such cases.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

There is at least one implementation, the basic idea behind the draft is rather straightforward.

## Additional Reviews

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

We do not think a review from other WGs is required. The WGLC went to the CBOR and HTTPAPI WGs as well.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

We have submitted the document for review of experts in media-types@iana and core-parameters@iana as well as the cbor-tags experts. The document was also reviewed by i18n experts.

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

Does not apply

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, ASN.1 modules, etc.

Yes, all examples have been validated.

Note & FYI: This comment is unrelated to the draft but for the benefit of readers trying CBOR and CDDL validation, not all implementations are up to date with the standard. https://github.com/anweiss/cddl/issues/122

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, the document has gone through multiple reviews and the current text is clear and complete.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

Not to my knowledge.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

The document is Standards Track, it is intended to be a normative reference.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. There is no known IPR.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes they have.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There not seem to be any nits remaining in v-08.

15. Should any informative references be normative or vice-versa?

Most of the references are normative and they seem correctly so. There is an informative reference to rfc7807bis but a normative to rfc7807, this make sense as the new bis document may take a while to become RFC. The reference is to RFC 7807 only.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

All normative references are available. Yes, the community had sufficient access to review.

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

All references are RFCs, STDs or IANA.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

There are none.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

Does not apply.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

Section 5 with the IANA considerations defines:
a "Standard Problem Detail Key registry", a "Custom Problem Detail Key registry", a new media type, a new content format and a new CBOR tag. The text is clear and the registries look like the right ones (core-parameters, media-types and cbor-tags).

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

There are two new IANA sub-registries in the CoRE parameters registry: the "Standard Problem Detail Key registry" and the "Custom Problem Detail Key registry". The allocation is FCFS, but if experts were needed for review, the same reviewers as for other subregistries could be used: Carsten Bormann, Jaime Jimenez, Christian Amsüss, Klaus Hartke and also Thomas Fossati.

# Problem-details write-up

Based on [8-02-22 Shepherd Writeup Template ](https://chairs.ietf.org/documents/qa-style-writeup-template)

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

The document has reached sufficient and broad agreement in the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

Before IESG evaluation, within the working group, there were no controversial parts. Two alternative proposals where presented (bundled and unbundled) and one was agreed upon.
After IESG evaluation, there was in-depth discussion about the appendix of the document, triggered by the ART ART/i18ndir review. That resulted in the removal of the CDDL in the appendix, and in some discussion about splitting the document between the main body and the appendix. After discussion and the addition of a clarifying paragraph about future updates to either part of the document, there was rough consensus to keep the document as is.

## Common Part

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

We are not aware of any such cases.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

There is at least one implementation, the basic idea behind the draft is rather straightforward.

## Additional Reviews

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

We do not think a review from other WGs is required. The WGLC went to the CBOR and HTTPAPI WGs as well.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

We have submitted the document for review of experts in media-types@iana and core-parameters@iana as well as the cbor-tags experts. The document was also reviewed by i18n experts.

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

Does not apply

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, ASN.1 modules, etc.

Yes, all examples have been validated.

Note & FYI: This comment is unrelated to the draft but for the benefit of readers trying CBOR and CDDL validation, not all implementations are up to date with the standard. https://github.com/anweiss/cddl/issues/122

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, the document has gone through multiple reviews and the current text is clear and complete.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

Not to my knowledge.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

The document is Standards Track, it is intended to be a normative reference.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. There is no known IPR.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes they have.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There not seem to be any nits remaining in v-08.

15. Should any informative references be normative or vice-versa?

Most of the references are normative and they seem correctly so. There is an informative reference to rfc7807bis but a normative to rfc7807, this make sense as the new bis document may take a while to become RFC. The reference is to RFC 7807 only.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

All normative references are available. Yes, the community had sufficient access to review.

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

All references are RFCs, STDs or IANA.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

There are none.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

Does not apply.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

Section 5 with the IANA considerations defines:
a "Standard Problem Detail Key registry", a "Custom Problem Detail Key registry", a new media type, a new content format and a new CBOR tag. The text is clear and the registries look like the right ones (core-parameters, media-types and cbor-tags).

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

There are two new IANA sub-registries in the CoRE parameters registry: the "Standard Problem Detail Key registry" and the "Custom Problem Detail Key registry". The allocation is FCFS, but if experts were needed for review, the same reviewers as for other subregistries could be used: Carsten Bormann, Jaime Jimenez, Christian Amsüss, Klaus Hartke and also Thomas Fossati.

[Ballot comment]
Comments resolved by -06, original DISCUSS copied below:

Thanks to Yoav Nir for the secdir review. I agree with Yoav and would like to see his comment addressed:

The document defines a CBOR-encoded problem details structure, similar to the
JSON- or XML-encoded structure defined in RFC 7807. As such, the security
considerations for it mostly mirror those of RFC 7807, and that is all that the
Security Considerations section says.  Following this reference, the Security
Considerations section of 7807 urges caution when defining new problem types
for fear of leaking sensitive information in the relevant fields of new types.

There is, however, a difference between 7807 and this document. In 7807
different problems are identified by "type". In this document, there is no
explicit type. Instead, there are basic details that are defined, plus a
registry of standard and custom extra attributes that can be defined. The
security considerations section in 7807 is phrased in terms of new types.
Security considerations text written specifically for this documentation would
not mention new types (which don't exist), but new detail entries.

Still, the message would be the same. When defining new detail entries, care
should be taken that they do not leak sensitive information.  Yet because of
the difference, I believe that the text should be written specifically for this
document, not just referenced from 7807.

[Ballot comment]
Thanks for cleaning up the IANA Considerations items I mentioned in my DISCUSS.

With respect to the comment at the end of Section 5.4, is some other document altering the names of those registry columns?

[Ballot comment]
# GEN AD review of draft-ietf-core-problem-details-05

CC @larseggert

Thanks to Gyan S. Mishra for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/7aBXjJEt7iqTjvpIytdLkzToA3Y).

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Grammar/style

#### Section 3.2, paragraph 3
```
03:TS29112": { / cause / 0: "machine readable error cause", / invalidParams
                            ^^^^^^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

#### Section 3.2, paragraph 4
```
stered:/4711: { / cause / 0: "machine readable error cause", / invalidParams
                              ^^^^^^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

#### Section 5.1, paragraph 9
```
-parameters], with the policy "first come first served" [RFC8126]. Each entry
                                    ^^^^
```
It seems that a comma is missing.

#### "A.2.", paragraph 18
```
ise Problem Details data item in a similar way to the conversion described a
                              ^^^^^^^^^^^^^^^^
```
Consider replacing this phrase with the adverb "similarly" to avoid wordiness.

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool

[Ballot comment]
Thanks for working on this specification. It was a nice and quick read.

However, I found some inconsistencies in the IANA section. Specially section in 5.1 and 5.4.

In 5.1, I found lack of directives for the experts. And in 5.4, I didn't understand why the table columns need to different than how it is now in the IANA registry - Media type became Content type in this document. I saw the note in the 5.4 but also does not explain why it is different.

I can see Murray has already put discuss on those points. Hence supporting his discuss.

[Ballot discuss]
This should be quick to clear up, but the IANA Considerations section has a few issues:

Section 5.1 declares a new registry with a Specification Required policy.  RFC 8126 explains what this means in its Section 4.6, and notes that this will result in a Designated Expert being appointed, and further stipulates that "clear guidance to the designated expert should be provided when defining the registry".  However, none is evident here.  Was this an oversight?

Section 5.2 declares a new registry with a First Come First Served policy.  RFC 8126, Section 4.4, covers this, and says in pertinent part, "... in addition to the contact person field or reference, the registry should contain a field for change controller."  That's absent here, so please add one.

In Section 5.3, the "Required Parameters" and "Optional Parameters" need to be "N/A", not "None".  See RFC 6838, Section 5.6.

[Ballot discuss]
Thanks to Yoav Nir for the secdir review. I agree with Yoav and would like to see his comment addressed:

The document defines a CBOR-encoded problem details structure, similar to the
JSON- or XML-encoded structure defined in RFC 7807. As such, the security
considerations for it mostly mirror those of RFC 7807, and that is all that the
Security Considerations section says.  Following this reference, the Security
Considerations section of 7807 urges caution when defining new problem types
for fear of leaking sensitive information in the relevant fields of new types.

There is, however, a difference between 7807 and this document. In 7807
different problems are identified by "type". In this document, there is no
explicit type. Instead, there are basic details that are defined, plus a
registry of standard and custom extra attributes that can be defined. The
security considerations section in 7807 is phrased in terms of new types.
Security considerations text written specifically for this documentation would
not mention new types (which don't exist), but new detail entries.

Still, the message would be the same. When defining new detail entries, care
should be taken that they do not leak sensitive information.  Yet because of
the difference, I believe that the text should be written specifically for this
document, not just referenced from 7807.

IANA comment:

Section 5.2 is creating a First Come First Served registry, but it also requires "a reference document that provides a description of the map, including a CDDL description, that describes all inside keys and values."

IANA could check that a field called "Description" exists in the document, but we can't review the contents. If this information is required, this needs to be an Expert Review registry (or Specification Required, if the description in https://www.rfc-editor.org/rfc/rfc8126.html#section-4.6 sounds appropriate).

[Ballot comment]
Thank you for this document, and also for responding to Joel's OpsDir review -- https://datatracker.ietf.org/doc/review-ietf-core-problem-details-04-opsdir-lc-jaeggli-2022-06-06/

I have two comments (well, one comment and a nit):
1: Introduction: "It is designed to be reused by REST APIs, which can identify distinct shapes of these data items specific to their needs." - I like this description, but I initially went off trying to find if something (RFC7252, STD94, REST, etc) has described shapes before. Section 2 does a nice job of describing the term, but putting "shapes" in quotes in the introduction would have saved me some rabbit-holing...

2: Section 3.2 / Figure 3 has an example, which helped make this all a lot clearer to me. I think that it would be helpful to people not familiar with this topic to have an example much earlier in the document...

You can decide which of these is the comment, and which is the nit :-)

[Ballot comment]
** Section 1.
  It is designed to be reused by REST
  APIs, which can identify distinct shapes of these data items specific
  to their needs. 

I don’t understand the notion of “identif[ing] distinct shapes.”  Section 2 uses the terminology again.

** Section 2.  This section is called “Basic Problem Details”.  Is that something different than “Concise Problem Details”

** Section 2.
      It SHOULD
      NOT change from occurrence to occurrence of the same problem
      shape.

Is this guidance saying that things shouldn’t change on a per application basis, or something else?  As an aside, some comment on a “problem shape.”

** Section 2.

  The "detail" member, if present, ought to focus on helping the client
  correct the problem, rather than giving debugging information.

What is the difference between providing enough information to “correct the problem” vs. providing debugging information?

** Section 2.  Thank you for adding the base-lang to -05.  I was using -04 as the basis of my review and was going to mention BCP 18.  Should text be added to say that the base-lang and base-rtl are ignored if tag38 strings are used?

** Section 3.2
  Note that the URI given for the extension is for identification
  purposes only and, even if dereferenceable in principle, it MUST NOT
  be dereferenced in the normal course of handling problem details
  (i.e., outside diagnostic/debugging procedures involving humans).

Thank you for adding this text.  Consider clarifying the impact of this dereferencing by explaining that this could become a tracking mechanism.

** Section 4.  Given the instance and base-uri fields, and the flexibility in the extensions, it seems that there is a possibility this format to introduce URLs that could be dereferenced.  The standard cautions of Section 7 of RFC3986 would seem to apply if the client would follow them.

[Ballot comment]
Hi,

No real objection except that it feels like this is yet another part of the "HTTP stack" that is ported into COAP in a somewhat bespoke way.  I'm not convinced that the on the wire byte savings will end up being that great, considering that there still seems to be a reasonable amount of text returned in the error response.  Further, although the responses end up being machine readable, I'm not sure how easily peer software can really automatically handle those errors other than the error indicating that it is a transient response and hence potentially the operation could be retried.

But other than a slight rant, no actionable comments.

Regards,
Rob

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-core-problem-details-04. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are five actions which we must complete.

First, a new registry is to be created called the Standard Problem Detail Key registry. The new registry will be created on the Constrained RESTful Environments (CoRE) Parameters registry page located at:

https://www.iana.org/assignments/core-parameters/

The registry will be managed via Specification Required as defined by RFC 8126. There are initial registrations in the new registry as follows:

+=======+===============+========+======================+================+
| Key | Name | CDDL | Brief | Reference |
| value | | Type | description | |
+=======+===============+========+======================+================+
| -1 | title | text | short, human- | [ RFC-to-be ] |
| | | or | readable | |
| | | tag 38 | summary of the | |
| | | | problem shape | |
+-------+---------------+--------+----------------------+----------------+
| -2 | detail | text | human-readable | [ RFC-to-be ] |
| | | or | explanation | |
| | | tag 38 | specific to | |
| | | | this occurrence | |
| | | | of the problem | |
+-------+---------------+--------+----------------------+----------------+
| -3 | instance | ~uri | URI reference | [ RFC-to-be ] |
| | | | identifying | |
| | | | specific | |
| | | | occurrence of | |
| | | | the problem | |
+-------+---------------+--------+----------------------+----------------+
| -4 | response-code | uint | CoAP response | [ RFC-to-be ] |
| | | .size | code | |
| | | 1 | | |
+-------+---------------+--------+----------------------+----------------+
| -5 | base-uri | ~uri | Base URI | [ RFC-to-be ] |
+-------+---------------+--------+----------------------+----------------+

Second, a new registry is to be created called the Custom Problem Detail Key registry. The new registry will be created on the Constrained RESTful Environments (CoRE) Parameters registry page located at:

https://www.iana.org/assignments/core-parameters/

The registry will be managed via First Come, First Served as defined by RFC 8126. There are initial registrations in the new registry as follows:

+=======+=============+===========================+================+
| Key | Name | Brief description | Reference |
| value | | | |
+=======+=============+===========================+================+
| 7807 | tunnel-7807 | Carry RFC 7807 problem | [ RFC-to-be ] |
| | | details in a Concise | |
| | | Problem Details data item | |
+-------+-------------+---------------------------+----------------+

Third, in the application space of the Media Types registry located at:

https://www.iana.org/assignments/media-types/

a new registration is to be made as follows:

Name: concise-problem-details+cbor
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Fourth, in the CoAP Content-Formats registry on the Constrained RESTful Environments (CoRE) Parameters registry page located at:

https://www.iana.org/assignments/core-parameters/

a new registration will be made from the range 256-999 as follows:

Media Type: concise-problem-details+cbor
Encoding:
ID: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Fifth, in the CBOR Tags registry on the Concise Binary Object Representation (CBOR) Tags registry page located at:

https://www.iana.org/assignments/cbor-tags/

the existing registration:

Tag: 38
Data Item: array
Semantics: Language-tagged string
Reference: [http://peteroupc.github.io/CBOR/langtags.html][Peter_Occil]

will have its reference changed to [ RFC-to-be; Appendix A]

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

Michelle Thangtamsatid
IANA Services Specialist

The following Last Call announcement was sent out (ends 2022-06-10):

From: The IESG
To: IETF-Announce
CC: core-chairs@ietf.org, core@ietf.org, draft-ietf-core-problem-details@ietf.org, francesca.palombini@ericsson.com, jaime@iki.fi
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Concise Problem Details For CoAP APIs) to Proposed Standard


The IESG has received a request from the Constrained RESTful Environments WG
(core) to consider the following document: - 'Concise Problem Details For
CoAP APIs'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2022-06-10. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document defines a concise "problem detail" as a way to carry
  machine-readable details of errors in a REST response to avoid the
  need to define new error response formats for REST APIs for
  constrained environments.  The format is inspired by, but intended to
  be more concise than, the Problem Details for HTTP APIs defined in
  RFC 7807.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-core-problem-details/



No IPR declarations have been submitted directly on this I-D.

# Problem-details write-up

Based on [8-02-22 Shepherd Writeup Template ](https://chairs.ietf.org/documents/qa-style-writeup-template)

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

The document has reached sufficient and broad agreement in the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

There were no controversial parts. Two alternative proposals where presented (bundled and unbundled) and one was agreed upon.

## Common Part

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

We are not aware of any such cases.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

There is at least one implementation, the basic idea behind the draft is rather straightforward.

## Additional Reviews

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

We do not think a review from other WGs is required. The WGLC went to the CBOR and HTTPAPI WGs as well.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

We have submitted the document for review of experts in media-types@iana and core-parameters@iana as well as the cbor-tags experts.

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

Does not apply

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, ASN.1 modules, etc.

Yes, all examples have been validated.

Note & FYI: This comment is unrelated to the draft but for the benefit of readers trying CBOR and CDDL validation, not all implementations are up to date with the standard. https://github.com/anweiss/cddl/issues/122

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, the document has gone through multiple reviews and the current text is clear and complete.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

Not to my knowledge.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

The document is Standards Track, it is intended to be a normative reference.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. There is no known IPR.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes they have.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There not seem to be any nits remaining in v-04.

15. Should any informative references be normative or vice-versa?

Most of the references are normative and they seem correctly so. There is an informative reference to rfc7807bis but a normative to rfc7807, this make sense as the new bis document may take a while to become RFC. The reference is to RFC 7807 only.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

All normative references are available. Yes, the community had sufficient access to review.

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

All references are RFCs, STDs or IANA.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

There are none.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

Does not apply.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

Section 5 with the IANA considerations defines:
a "Standard Problem Detail Key registry", a "Custom Problem Detail Key registry", a new media type, a new content format and a new CBOR tag. The text is clear and the registries look like the right ones (core-parameters, media-types and cbor-tags).

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

There are two new IANA sub-registries in the CoRE parameters registry: the "Standard Problem Detail Key registry" and the "Custom Problem Detail Key registry". The allocation is FCFS, but if experts were needed for review, the same reviewers as for other subregistries could be used: Carsten Bormann, Jaime Jimenez, Christian Amsüss, Klaus Hartke and also Thomas Fossati.

# Problem-details write-up

Based on [8-02-22 Shepherd Writeup Template ](https://chairs.ietf.org/documents/qa-style-writeup-template)

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

The document has reached sufficient and broad agreement in the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

There were no controversial parts. Two alternative proposals where presented (bundled and unbundled) and one was agreed upon.

## Common Part

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

We are not aware of any such cases.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

There is at least one implementation, the basic idea behind the draft is rather straightforward.

## Additional Reviews

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

We do not think a review from other WGs is required. The WGLC went to the CBOR and HTTPAPI WGs as well.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

We have submitted the document for review of experts in media-types@iana and core-parameters@iana as well as the cbor-tags experts.

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

Does not apply

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, ASN.1 modules, etc.

Yes, all examples have been validated.

Note & FYI: This comment is unrelated to the draft but for the benefit of readers trying CBOR and CDDL validation, not all implementations are up to date with the standard. https://github.com/anweiss/cddl/issues/122

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, the document has gone through multiple reviews and the current text is clear and complete.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

Not to my knowledge.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

The document is Standards Track, it is intended to be a normative reference.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. There is no known IPR.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes they have.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There not seem to be any nits remaining in v-04.

15. Should any informative references be normative or vice-versa?

Most of the references are normative and they seem correctly so. There is an informative reference to rfc7807bis but a normative to rfc7807, this make sense as the new bis document may take a while to become RFC. The reference is to RFC 7807 only.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

All normative references are available. Yes, the community had sufficient access to review.

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

All references are RFCs, STDs or IANA.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

There are none.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

Does not apply.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

Section 5 with the IANA considerations defines:
a "Standard Problem Detail Key registry", a "Custom Problem Detail Key registry", a new media type, a new content format and a new CBOR tag. The text is clear and the registries look like the right ones (core-parameters, media-types and cbor-tags).

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

There are two new IANA sub-registries in the CoRE parameters registry: the "Standard Problem Detail Key registry" and the "Custom Problem Detail Key registry". The allocation is FCFS, but if experts were needed for review, the same reviewers as for other subregistries could be used: Carsten Bormann, Jaime Jimenez, Christian Amsüss, Klaus Hartke and also Thomas Fossati.

# Problem-details write-up

Based on [8-02-22 Shepherd Writeup Template ](https://chairs.ietf.org/documents/qa-style-writeup-template)

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a few individuals, with others being silent, or did it reach broad agreement?

The document has reached sufficient and broad agreement in the group.

2. Was there controversy about particular points, or were there decisions where the consensus was particularly rough?

There were no controversial parts. Two alternative proposals where presented (bundled and unbundled) and one was agreed upon.

## Common Part

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

We are not aware of any such cases.

4. For protocol documents, are there existing implementations of the contents of the document? Have a significant number of potential implementers indicated plans to implement? Are any existing implementations reported somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere (where)?

There is at least one implementation, the basic idea behind the draft is rather straightforward.

## Additional Reviews

5. Does this document need review from other IETF working groups or external organizations? Have those reviews occurred?

We do not think a review from other WGs is required. The WGLC went to the CBOR and HTTPAPI WGs as well.

6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

We have submitted the document for review of experts in media-types@iana and core-parameters@iana as well as the cbor-tags experts.

7. If the document contains a YANG module, has the final version of the module been checked with any of the recommended validation tools for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC 8342?

Does not apply

8. Describe reviews and automated checks performed to validate sections of the final version of the document written in a formal language, such as XML code, BNF rules, MIB definitions, CBOR's CDDL, ASN.1 modules, etc.

Yes, we have checked the CDDL of figure 2 and that of the examples and they are compliant with the CDDL which is validated against the RFC7807.
Note & FYI: There is an outdated implementation out there that would throw errors: https://github.com/anweiss/cddl/issues/122

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this document is needed, clearly written, complete, correctly designed, and ready to be handed off to the responsible Area Director?

Yes, the document has gone through multiple reviews and the current text is clear and complete.

10. Several IETF Areas have assembled lists of common issues that their reviewers encounter. Do any such issues remain that would merit specific attention from subsequent reviews?

Not to my knowledge.

11. What type of RFC publication is being requested on the IETF stream (Best Current Practice, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent?

The document is Standards Track, it is intended to be a normative reference.

12. Has the interested community confirmed that any and all appropriate IPR disclosures required by BCP 78 and BCP 79 have been filed? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails.

Yes. There is no known IPR.

13. Has each Author or Contributor confirmed their willingness to be listed as such? If the number of Authors/Editors on the front page is greater than 5, please provide a justification.

Yes they have.

14. Identify any remaining I-D nits in this document. (See the idnits tool and the checkbox items found in Guidelines to Authors of Internet-Drafts). Simply running the idnits tool is not enough; please review the entire guidelines document.

There not seem to be any nits remaining in v-04.

15. Should any informative references be normative or vice-versa?

Most of the references are normative and they seem correctly so. There is an informative reference to rfc7807bis but a normative to rfc7807, this make sense as the new bis document may take a while to become RFC. The reference is to RFC 7807 only.

16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references?

All normative references are available. Yes, the community had sufficient access to review.

17. Are there any normative downward references (see RFC 3967, BCP 97)? If so, list them.

All references are RFCs, STDs or IANA.

18. Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If they exist, what is the plan for their completion?

There are none.

19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs listed on the title page, in the abstract, and discussed in the introduction? If not, explain why and point to the part of the document where the relationship of this document to these other RFCs is discussed.

Does not apply.

20. Describe the document shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all aspects of the document requiring IANA assignments are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, allocations procedures, and a reasonable name (see RFC 8126).

Section 5 with the IANA considerations defines:
a "Standard Problem Detail Key registry", a "Custom Problem Detail Key registry", a new media type, a new content format and a new CBOR tag. The text is clear and the registries look like the right ones (core-parameters, media-types and cbor-tags).

21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? Please include suggestions of designated experts, if appropriate.

There are two new IANA sub-registries in the CoRE parameters registry: the "Standard Problem Detail Key registry" and the "Custom Problem Detail Key registry". The allocation is FCFS, but if experts were needed for review, the same reviewers as for other subregistries could be used: Carsten Bormann, Jaime Jimenez, Christian Amsüss, Klaus Hartke and also Thomas Fossati.