Re: [core] [Cbor] WG Last Call on draft-ietf-core-problem-details

[Carsten Bormann <[e-mail]>]

Hi Marco,

> Please find below my review comments.

A pull request based on this is at

https://github.com/core-wg/core-problem-details/pull/18
> 
> Best,
> /Marco
> 
> 
> 
> [Section 1.1]
> 
> * Please add the usual remark "Readers are expected to be familiar with ..."

I added the usual suspects; maybe we should have a second look what else needs to be there.

> [Section 2]
> 
> * The caption of Figure 2 can better say "Concise Problem Details Data Item".

Indeed, we should standardize on one way to say this.  Inevitably, people will create abbreviations here, which would be “CPDDI”…

> * The definition of the 'title' entry says: "It SHOULD NOT change from occurrence to occurrence of the problem."
> 
>    Do you mean "of the same problem" ?

Kind of: :-)
I mean “same kind of problem”.  Discussion below.

> * The definition of 'response-code' can be expanded to also point to Section 3 of RFC 7252, and explicitly say that the response code here is exactly the value of the 'Code' field in the header of the CoAP response. This would complement the statement and example in the last paragraph of the section.

(This is now mentioned in the last paragraph of Section 2.)

> * When defining the entry 'response-code', it is good to have a pointer also to Section 3.2 of RFC 8132, thus covering also 4.09 and 4.22.

I instead added a reference to 12.1.2 (IANA Considerations: response codes) of 7252, so this is more future proof.

> * "Note that, unlike [RFC7807], Concise Problem Details data items have no explicit type."
> 
> Consistently, please consider the following changes to avoid possible confusion:
> 
>    - In Section 1, use "problem classes" rather than "problem types".

In the DT meeting, we were struggling for a term.
We came up with “problem shape”, which is weird enough that it is easily recognizable as a separate term.
Text added.

>    - In Section 2, use "summary of the problem class" rather than "summary of the problem type" when defining the 'title' entry. A few paragraphs below, "shorthand for the category of the error" can also become "shorthand for the class of the error".
> 
>    - In Section 3, use "generic problem class container" rather than "generic problem type container".
> 
>    - In Section 5.1, as to the "Brief description" for 'title' in Table 1, use "problem class" rather than "problem type".

All done, in a way.

> [Section 3.1]
> 
> * "Consumers of a Concise Problem Details instance MUST ignore ..."
> 
>    I think it is better to use "data item" rather than "instance". That would be consistent with the text in other sections and would avoid confusion with the 'instance' entry.

Indeed.

> [Section 3.2]
> 
> * "Consumers of a Concise Problem Details instance MUST ignore ..."
> 
>    See the comment above about using "data item" rather than "instance".
> 
> * Is it admitted to change the definition of an already existing Custom Problem Details entry, by updating the related documentation? Or is it something to discourage or even forbid, rather preferring a new entry to be defined altogether?

That is indeed an important consideration, which -03 touched only.
We added some text.


> [Section 5.1]
> 
> * For 'title' and 'detail', shouldn't the CDDL Type be "text/array", rather than "text"? If tag 38 is used, that applies to an array, as per Appendix A.2.

Changed to “text or tag 38”.
> 
> 
> [Nits]
> 
> * Section 3.1, s/so they never can/so they can never
> 
> * Section 3.2, s/the nested map any/the nested map, any
> 
> * Section 3.2, s/for extension that/for extensions that
> 
> * Section 3.2, s/compact representation, in/compact representation. In
> 
> * Section 3.2, s/principle, MUST NOT be/principle, it MUST NOT be
> 
> * Section 5.1, s/Entries in Standard/Entries in the Standard
> 
> * Section 5.2, s/Entries in Custom/Entries in the Custom
> 
> * Table 1/2/3, s/RFCXXXX/RFC XXXX
> 
> * Appendix B (2 instances), s/Concise Problem Details item/Concise Problem Details data item
> 
> * Appendix B (2 instances), s/Custom Problem Detail entry/Custom Problem Details entry

Thank you!

Grüße, Carsten