[Last-Call] Artart last call review of draft-ietf-core-problem-details-05

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Reviewer: Harald Alvestrand
Review result: On the Right Track

Review of Concise Problem Details for CoAP APIs -
draft-ietf-core-problem-details-05

Status: On the right track, but needs work.

This is a joint i18n and apps review (since I was assigned as reviewer for
both).

Summary of conclusions
I recommend that this document be broken into two documents: An error format
and an internationalized string format.

A number of other, less important, issues are described 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
* An “explanation” - human readable
* An “instance” - an URI
* 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; 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.

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

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.

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.

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

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.

Second, the “detailed semantics” has chosen to include the quite complex BNF of
RFC 5646 translated into CDDL; this may have some use, but BCP 47 is a moving
target; having CDDL parsers try to validate tags according to this grammar is
not going to be useful. If included at all, this needs to be clearly marked
with text saying that BCP 47 is normative for this grammar, and that language
tag parsers should NOT try to reject tags based on this grammar; instead, they
should be treated as strings, and looked up against relevant language handling
APIs. (“zh-ZZ” is perfectly valid according to the grammar, but is semantically
invalid according to BCP 47). Note also that the sentence “Data items with tag
38 that do not meet the criteria above are invalid (see Section 5.3.2 of
[STD94]).” is really hard to parse semantically, given that section 5.3.2 of
RFC 8949 doesn’t use the word “invalid”, it uses “inadmissible value”. I do not
recommend rejecting unknown language tags.

Thirdly, the definition of the tri-state direction attribute can be made
clearer; in particular, the Unicode Bidirectional Algorithm (UAX#9) should be
referenced, with particular reference to
https://www.unicode.org/reports/tr9/tr9-44.html#Markup_And_Formatting - the
important property here is that the desired semantic is isolation - the markup
is intended to have zero influence on strings outside the embedded string - the
semantics of embedding in RLI…PDI is the desired effect.

Issues with referencing Appendix A from the main body

The reference from the main body of the document in the context of the (version
5 added) language and bidi attributes is also not clear; it is probably
intended to say “if the default attributes are given, then each attribute with
the grammar of “oltext” is to be interpreted as a Tag 32 string with the
corresponding attributes set”.

This creates an issue with strings defined in custom-problem-detail-entries:
one has to know whether a particular attribute is “oltext” in order to know
whether the default lang and rtl attributes apply or not.


-- 
last-call mailing list
last-call@xxxxxxxx
https://www.ietf.org/mailman/listinfo/last-call




[Index of Archives]     [IETF Annoucements]     [IETF]     [IP Storage]     [Yosemite News]     [Linux SCTP]     [Linux Newbies]     [Mhonarc]     [Fedora Users]

  Powered by Linux