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
