Re: [core] Roman Danyliw's No Objection on draft-ietf-core-problem-details-05: (with COMMENT)

[Carsten Bormann <[e-mail]>]

Hi Roman,

thank you for this review.

All the changes mentioned below are part of https://github.com/core-wg/core-problem-details/pull/35 — an editor’s copy is at https://core-wg.github.io/core-problem-details/rd-comments/draft-ietf-core-problem-details.html .

Grüße, Carsten


> On 2022-06-13, at 16:57, Roman Danyliw via Datatracker <[e-mail]> wrote:
> 
> Roman Danyliw has entered the following ballot position for
> draft-ietf-core-problem-details-05: No Objection
> […]
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-core-problem-details/
> 
> 
> 
> ----------------------------------------------------------------------
> 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.

The term “shape” is often used to describe the structure of a data item used in interchange.  E.g., there is a 2017 W3C recommendation for a “Shapes Constraint Language (SHACL)”.  The English language sense of this term should suffice until we define “problem shape” (see below).

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

Good point.
Section 2 defines both the overall structure of Concise Problem Details data items and the most important, predefined Standard Problem Detail entries, so it is juxtaposed against Section 3, Extending Concise Problem Details.

We could call it “Structure of and basic entries in Concise Problem Details”?
This gets a bit unwieldy.

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

We changed this text from -04 to -05, see https://www.ietf.org/archive/id/draft-ietf-core-problem-details-05.html#section-2-5.2.1

We still would like to stick with the term “problem shape”, which is explained in https://core-wg.github.io/core-problem-details/draft-ietf-core-problem-details.html#section-2-4 — it seems that this concept can be unfamiliar to many so it may require more text.

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

Debugging information is meant here in terms of details of the server side operation.
We could say that.

Changed that to …”rather than giving extensive server-side
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?

We think we already say this ("presentation of unadorned text strings”, “Language tag and writing direction information for unadorned text strings …”), but the negative could be more explicit; we added “not using tag 38”.

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

Added a paragraph in the Security Considerations.

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

Added a reference to Section 7 of RFC 3986 to the Security Considerations.