Re: [spec-reviews] http-problem (#37)

Here's what I got. Should I deliver it to apps-discuss, or pull request it here, or should we workshop it first, or...?

A proposal along these lines is sorely needed on the web, as explained very well by its introduction. My main concerns are around the confusing nature of type, title, and message fields, and how they might not be suited for common use cases.

My first concern is the recommendation that "type" be a dereferenceable URL. I think many APIs will simply want to have a unique-within-their-API ID per problem type, but that seems to be implicitly discouraged by this document, which wants them to mint new HTTP-accessible HTML pages describing the problem. I understand how it's very nice to have this kind of self-describing type, similar to link relations. But I worry that the additional burden will discourage people from using this format, or will end up with them putting non-URLs in the type field.

I'm also unsure how to make sense of the combination of "title" plus "detail". Given that both are meant to be human-readable, when is the separation helpful? What is the recommended way to display this to humans: title, two newlines, then detail, perhaps? Most error-communication systems in programming langauges have a machine-readable type (e.g. `TypeError`, `IOError`, etc.) and a single human-readable string (often `message`). I would venture a guess that many developers model their conception of errors similarly. Introducing two human-readable fields makes it harder to conceptualize how this is supposed to map to existing systems, or how to display the resulting error to the user. Ideally, I think, there would be a single "message" field, which could be mapped to that same field in most programming languages.

The "instance" field seems to be of unclear utility. In which scenario would this be useful? Is it worth making it part of the spec, instead of letting it be a per-scenario extension? How do you envision it being generically processed?

The optional "status" field seems fragile, as mentioned in section 5. What is the purpose of including it, especially since it is optional?

Finally, I'm unsure how comfortable I am with the lack of constraints on extension members. It might be more future-proof, or perhaps just cleaner, to separate them into a sub-object (`{ "type": ..., "title": ..., "other": { "customer_id": ... } }` or similar). Or, simply mandate that they must begin with a given prefix (an underscore, `"other_"`, `"details-"`, ...).

All in all though, this is really exciting. If it takes off, you could imagine it having ripple effects across web architecture. For just one example, you could imagine a built-in option to fetch that will use a application/problem+json response to construct a JavaScript `Error` object with its fields appropriately pre-filled, and reject the resulting promise instead of relying on a status-code-then-parse-error path in the fulfillment handler. Or, if the URL-based error identifier approach really takes off, you could imagine it helping solve [our problem in JavaScript of identifying errors more precisely](https://esdiscuss.org/topic/error-objects-in-w3c-apis#content-4).

---
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/spec-reviews/issues/37#issuecomment-84008225