Harald: thank you very much for this in depth double review!
I am looking forward to your reply to Carsten’s answer below (for some reason it is truncated in my local version, but I read the mailarchive one), but just on one point, since it also had come to
me when reviewing the document – you do suggest this document be split in two, the error format and the internationalized string format. I considered that too, but seeing that the CBOR tag is already registered, and this document merely updates that definition
and the reference, I evaluated that it was ok to have it in one document; moreover in this way you have both the tag and one example of the tag in usage in the same doc, I think that is valuable. If you think Appendix is considered less important, I would
not object to moving it into a main section of the document.
Thanks,
Francesca
From: Carsten Bormann <cabo@xxxxxxx>
Date: Wednesday, 15 June 2022 at 18:23
To: Harald Alvestrand <harald@xxxxxxxxxxxxx>
Cc: art@xxxxxxxx <art@xxxxxxxx>, core@xxxxxxxx <core@xxxxxxxx>, draft-ietf-core-problem-details.all@xxxxxxxx <draft-ietf-core-problem-details.all@xxxxxxxx>, last-call@xxxxxxxx <last-call@xxxxxxxx>
Subject: Re: [art] Artart last call review of draft-ietf-core-problem-details-05
Hi Harald,
thank you for this thoughtful review.
A number of the considerations listed are already solved by the underlying standards CoAP, CBOR, and CDDL; I’ll try to explain this in context, and get to the other observations.
> Summary of conclusions
> I recommend that this document be broken into two documents: An error format
> and an internationalized string format.
(I’ll get to this below.)
> Summary of content
>
> This document defines an error reporting format for use with REST APIs using
> COAP as their response format. Note: This reviewer does not know COAP, so the
> appropriate usage of COAP is not checked in this review.
>
> The standardized form of the response consists of:
> * A “problem shape” - human readable
The “title” field is the human-readable part; the problem shape is the shape of the problem details as presented that can be recognized by an automated mechanism.
> * An “explanation” - human readable
This (“detail” field) goes into instance-specific details.
> * An “instance” - an URI
E.g., a shopping basket etc.
> * A “response code” (ref RFC 7252), a 2-level code mimicking the 2xx/4xx/5xx
> system (IANA registry) * A “base URI” that is only for internal usage * (added
> in -05): base-lang and base-rtl It is not clear to this reviewer from the
> document whether these fields are mandatory or optional;
The fields are all optional, hence the non-empty<…> to say at least one of them needs to be there (or the whole thing is pointless). They are optional because the context (specifically, the URI in the request providing the base URI, and the response code in
the response providing the response-code) often provides them, and this format is intended to be concise.
> if the question mark
> in front of the fields is “optional”, then there is no mandatory field in the
> details at all; rather, the “non-empty” notation seems to mean that there
> should be *something* in it. So an error report consisting of just base-rtl is
> syntactically legal.
(But not very useful.)
It is usually hard to capture semantic constraints in a structural language like CDDL (or ABNF), so we didn’t try.
> The report may be extended with standard or app-specific details - identified
> with negative numbers (standard), positive numbers (registered) or URIs.
>
> Appendix A defines the “Tag 38” string format, which decorates a string with
> language and direction attributes.
>
> Usability as an error format
> The general treatment of an error consists of two processes:
> * The client receiving the error takes an automatic action based on the error
> content. For this to work well, the error needs to be machine parsable and
> clearly indicate the appropriate action to be taken (in the context of the
> application).
Right, this is where the standard or custom problem details come in and provide the problem shape that the application can react on.
> * The user reports an error that was unexpected and not handled
> by the client to the developer or support personnel that can use other
> processes to figure out why there was a problem and give (human) advice. For
> this to work well, the error has to be capable of being picked up by the human
> and transmitted to the issue investigator.
CoAP already has the concept of diagnostic payloads (specified to be UTF-8 strings), so this is already covered; the present draft provides a structure that can be used instead of these unstructured payloads.
> This error format is somewhat capable of doing both, but its great
> extensibility and lack of required parts serves to make it difficult to know
> whether it’s actually useful for both.
It is hard to define “useful” exactly. We expect common usages of this format will emerge, but it would be too early to standardize these. Instead, we provide a framework inside which these usages can evolve in an interoperable way.
> The document does not contain any advice on how to make the format useful for
> these two purposes when used with a specific application. This is a weakness.
The document would need to list all those applications, and more specific advice might also be too early to standardize.
> Specific guidance that could be included:
>
> * When an error can be handled automatically, always include a COAP response
> code, even if it is only “5.00 internal error”.
The response code is usually provided in the CoAP response already, so there is no need to deliver it in the payload. Only when problem details are stored/forwarded is it a good idea to set response-code, base-uri etc.
to save the (implicit) transaction context that would otherwise be lost.
> If an application specific
> action is desired (like “refresh your credentials” in an authorized action),
> use a registered custom problem detail number or a custom problem detail URI.
The general action may also be implied by the response code, e.g. 4.01 Unauthorized (really: Unauthenticated, but we inherit this misnomer from HTTP), or 4.03 Forbidden (really: Unauthorized).
> *
> When an error may need to be reported, make sure that it can be fully
> represented in a text format that can be copy/pasted into an error report
As Section 3.1.1 demonstrates, human-readable text form is often not needed, so I’m not sure we should give this advice.
> *
> When an error may need to be reported, makes ure that any personally
> identifiable information (PII) is either obvious to the casual viewer or
> omitted from the report. In particular, do NOT include PII in encoded formats
> like Base64.
Good point!
We added a brief Privacy Considerations section and expanded the Security Considerations section in
https://protect2.fireeye.com/v1/url?k=31323334-501d5122-313273af-454445555731-762cab0b21555e42&q=1&e=5ccc0dd6-e0d8-481a-a32c-b39bca5b77b6&u=https%3A%2F%2Fgithub.com%2Fcore-wg%2Fcore-problem-details%2Fpull%2F34 — editor’s copy at
https://protect2.fireeye.com/v1/url?k=31323334-501d5122-313273af-454445555731-492c71a889cc066b&q=1&e=5ccc0dd6-e0d8-481a-a32c-b39bca5b77b6&u=https%3A%2F%2Fcore-wg.github.io%2Fcore-problem-details%2Fprivcons-seccons%2Fdraft-ietf-core-problem-details.html%23name-privacy-considerations).
> Unless some guidance of this kind is included, I fear that the applications of
> the concise error format will be so diverse as to make the “commonality” less
> useful.
>
> The “Tag 38 internationalized string”
> This document adds an appendix defining an “internationalized string” format
> that adds a BCP 47 language tag and an Unicode-based direction indicator to an
> UTF-8 string. This is laudable; RFC 2277 section 4 pointed out the need for
> this ability 24 years ago.
>
> Unfortunately neither definition is problem-free.
>
> First of all, this tag, if useful at all, is of far greater utility than the
> error format. Burying it in an appendix of a document whose stated purpose is
> something else makes it far more difficult to refer to than it needs to be.
That is usually not a problem. The focal point for finding a CBOR tag for a specific application is the CBOR tag registry; this then points to the places where the specifications for the tags can be found (which in this case is easily expressed as “Appendix
A of RFC XXXX”)
|
