Problem Details Object for Warning

[sdatspun2]

Capturing @ioggstream's response from email thread with follow up questions. Should Problem Details JSON Object schema have any member indicating that the problem(s) is an error(s) or warning(s)? If yes, which status code(s) could be used in case of warning.

On Tue, Jan 19, 2021 at 12:30 AM Roberto Polli <roberto@> wrote: I would like to find a convergent solution for both Problem and Content-Warning, eg. see https://github.com/dret/I-D/blob/master/http-warning/draft-cedik-http-warning-02.txt#L295 which proposes the use of a list of Problem.json which - imho - provide redundant information (eg. status should always be the same).

Kind regards, R.

Roberto Polli API Expert

[mnot]

My initial thought is that the problem type itself should indicate this (e.g., in its documentation). The term 'problem' was used very deliberately, to cover both (and perhaps more).

Is there a use case for software generically sifting things considered "warnings" from "problems" without knowing anything specific about the type? If so, more details about it would help drive the design here.

Also, if we go down this road, should we be considering a 'level' parameter?

[andrecedik]

I've contacted Erik to see if it would be best to put our ideas and efforts into rfc7807bis instead of the I-D. Haven't heard from him back though.

I have to agree with Mark when he's saying:

The term 'problem' was used very deliberately, to cover both (and perhaps more).

From my point of view: I'd rather see a solution in rfc7807bis than trying to recreate the wheel since errors and warnings both are conveying information an API client might need to function properly or communicate to the end user. Having two separate ways of handling these situations makes API design more complicated.

Also, if we go down this road, should we be considering a 'level' parameter?

What do you have in mind @mnot? Something like a log level (error, warn, info, debug)?

[ioggstream]

if it would be best to put our ideas and efforts into rfc7807bis instead of the I-D

@andrecedik I think that disentangling the ~Warning I-D from the content will still be useful and could move further, though.

[andrecedik]

Yes @ioggstream, that could be the (only) reason for keeping the I-D alive. Throw out the proposed format for the body and just introduce the warning header field.

[sdatspun2]

If yes, which status code(s) could be used in case of warning.

https://tools.ietf.org/html/draft-cedik-http-warning-02#section-6 suggests using 2xx

Since warnings do not have an effect on the returned HTTP status code, the response status code SHOULD be in the 2xx range, indicating that the intent of the client was successful.

https://tools.ietf.org/html/rfc7807#section-1 Thus, API clients can be informed of both the high-level error class (using the status code) and the finer-grained details of the problem (using one of these formats).

high-level error class means 4xx and 5xx (https://www.iana.org/assignments/http-status-codes/http-status-codes.xml)

As a consumer of an API, I would not imagine scenarios having a response with HTTP status as 400 and having 200 in the response body (top level or in the proposed contained problem(s)) with the proposed level as warning. Having a status in the response body already creates a situation that needs explanation in https://tools.ietf.org/html/rfc7807#section-5. Adding the warning scenario in the mix will make it even more complex to explain imo and most importantly for no practical use case perhaps.

My initial thought is that the problem type itself should indicate this (e.g., in its documentation). The term 'problem' was used very deliberately, to cover both (and perhaps more).

I agree that this differentiation should be left to the documentation.

[serialseb]

The scenario i envision is one where problem documents are persisted, and then shared across other systems, or visualised in a log viewer, all of which tend to have a minimum amount of standard behaviours. One would be displaying a ⚠ or ⛔️ or what not for operators, another would be alerting differently based on the severity of a problem document.

[mnot]

The scenario i envision is one where problem documents are persisted, and then shared across other systems, or visualised in a log viewer, all of which tend to have a minimum amount of standard behaviours. One would be displaying a ⚠ or ⛔️ or what not for operators, another would be alerting differently based on the severity of a problem document.

Is that information associated with the problem instance or the problem type?

It strikes me that it might be useful to start thinking about a problem type description document format that can be fetched from the type URI; that would be able to convey this information, documentation in a machine-readable format that can be used by tooling, etc.

It would also avoid the extension problem noted in https://github.com/ietf-wg-httpapi/rfc7807bis/issues/15#issuecomment-886360909

Doing so would give type definitions an incentive to make their URIs resolvable, rather than just 404.

[SleeplessByte]

Nothing prevents us from Accept: x/y for a machine readable format on those type urls, right? We currently serve text/html, but looking at our systems, we could actually serve some machine readable format after content-neg.

[mnot]

@SleeplessByte nope :)

[mnot]

Should we define such a format in an appendix of this spec, or punt it down the road? Thoughts?

[dret]

On 2021-10-11 02:15, Mark Nottingham wrote:

Should we define such a format in an appendix of this spec, or punt it down the road? Thoughts?

having worked on a draft for this, there is some work we could use, but then again i'd prefer to see that being part of a spec. but maybe having it as an appendix is better than not having anything at all, so i am slightly in favor of such an appendix.

[sdatspun2]

Should we define such a format in an appendix of this spec, or punt it down the road? Thoughts?

Since warnings are sent with 200 which is never used to respond with error(s), I am not sure how warnings could be accommodated here. Having said that, I am open to reviewing the text in appendix.

[andrecedik]

You could combine the warnings with the Content-Warning field proposed in the draft @dret mentioned, thus making it possible to react to its presence although the HTTP status code is 200.

[sdatspun2]

can you provide a sample that includes both warnings and errors in the same response? sample would help. looked at the draft which only shows example of warning. thanks.

[mnot]

@sdatspun2 see above - the thinking is that we can define a format that you retrieve from the problem type URI to get more information about that problem type -- including things like warning levels.

[dret]

On 2021-10-12 00:34, Mark Nottingham wrote:

@sdatspun2 https://github.com/sdatspun2 see above - the thinking is that we can define a format that you retrieve from the problem type URI to get more information about that problem type -- including things like warning levels.

that's not quite what the warning draft/effort was all about. that one was all about communicating warnings at runtime in a way similar to what RFC 7807 does, but without being a critical error.

if we're looking at other aspects such as representing a problem type description, then maybe we can call it something different than "warning information"? maybe it's just me getting confused because of the work on the warning message draft, but maybe others find it confusing as well.

[mnot]

@dret do you have concrete proposals for changes in this draft? Looking at the issue above, I don't think we've gone off track here...

[dret]

i think we're mixing two things here, and the issue title of "Problem Details Object for Warning" doesn't help.

• there is a (expired) draft that defines a Content-Warning header field and a suggested format to be used as a building block in JSON formats. feedback regarding that draft let @andrecedik and myself to believe that maybe the JSON format is not needed, which would leave just the Content-Warning header field. this is mostly about allowing servers to say that they served a request, but that there are some issues that a client might want to look at. we could add the section defining the header field to 7807bis, but that would slightly change the scope of the spec because it now also would talk about things to be done when a problem is just a warning and not an error.
• most of the discussions in this issue here seem to center around either a format for representing problem report instances or problem report types. both of these may be useful things to have, but in my mind are fairly different from the scenario that i initially thought this issue is about. but i may have misunderstood the title from the very beginning.

to answer your question, @mnot: i think adding the Content-Warning field could be useful as a way to provide mechanism for a slightly wider range of problems, but that proposal doesn't seem to be what most people are discussing here. the downside of doing this could be that it might require quite a bit of reworking of the draft to make sure that it covers the scenario of requests being served with success status codes, but with some warning information included. the upside would be that the handling of types could be unified across the Content-Warning field's type (which currently uses a mechanism with a registry but that of course can be changed) and the type member of the problem report format.

[mnot]

OK. If we want to finish this quickly and avoid scope creep, we should probably punt both the header and the format to separate drafts. What do folks think - is this something that needs to ship with rfc7807bis?

[dret]

On 2021-10-19 05:07, Mark Nottingham wrote:

OK. If we want to finish this quickly and avoid scope creep, we should probably punt both the header and the format to separate drafts. What do folks think - is this something that needs to ship with rfc7807bis?

imho it's not something that needs to be part of the draft. it definitely would extend the scope (but in a good way, i think).

[sdatspun2]

+1

If we want to finish this quickly and avoid scope creep, we should probably punt both the header and the format to separate drafts

[mnot]

Based upon the above, closing - please say so if you disagree / have more info.