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

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?

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.

** 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.

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 :-)

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.

# 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

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