Extension to show source of problem in request for 4xx class of errors

[sdatspun2]

Example added for multiple problems shows use of an extension called property_location which is a JSON Pointer RFC6901 that points to the source of the problem in the corresponding HTTP request. Such an extension could only be used to show source of problem in 4xx class of errors such as Bad Request. HTTP request validation errors are the most common and most frequent client side error in HTTP APIs.

Opening this issue on suggestion of @asbjornu...

Although property_location is just added as an example extension, having it in the specification gives it weight and authority. For something like this to be added (even if only as an extension to an example) I think it needs to be thoroughly discussed in a separate issue first.

[dret]

On 2021-10-16 21:41, Sanjay Dalal wrote:

Example added for multiple problems shows use of an extension called |property_location| which is a JSON Pointer RFC6901 that points to the source of the problem in the corresponding HTTP request. Such an extension could only be used to show source of problem in 4xx class of errors such as Bad Request. HTTP request validation errors are the most common and most frequent client side error in HTTP APIs.

still agreeing with @asbjornu that the examples may not be the best place to try to be creative in ways that need a lot of explanation. after all, we want to show how to use the spec and not speculate about what people might add on.

iff we go the creative route, my preferred naming choice would be something along the lines of "problem-pointer" to leave it independent of the payload format and relate it to the name of the problem spec.

[sdatspun2]

Makes sense. +1

iff we go the creative route, my preferred naming choice would be something along the lines of "problem-pointer" to leave it independent of the payload format and relate it to the name of the problem spec.

[mnot]

Can this be closed?

[dret]

On 2021-11-12 12:36, Mark Nottingham wrote:

Can this be closed?

i think so since we haven't seen an actual proposal for this.

[sdatspun2]

Hold on please. I have given example in https://github.com/ietf-wg-httpapi/rfc7807bis/issues/32. Not sure if additional proposal was needed.

[mnot]

Note that adding a new member has potential issues; see https://github.com/ietf-wg-httpapi/rfc7807bis/issues/15#issuecomment-886360909

[darrelmiller]

We seem to be in a catch-22 here. We can't add it as a standard property in the specification because that would require a new media type and it has been asserted that we should not use examples to suggest how people might extend the specification.

Where does this leave us? Should we consider a complementary "best practices" document that suggests ways in which errors could be extended? Would this also help to address the multiple problems issue? #6

[awwright]

It seems to me that there should have been a mechanism for forward compatibility. For example, that non-standard/user keywords must be a (full) URI, and names (e.g. /[a-z0-9]+/) have a standard meaning. If we can't do that without breaking backward compatibility, well then I don't see a problem with a new media type.

[dret]

my vote still goes to avoiding speculative examples. the built-in extension mechanism (https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-rfc7807bis#section-3.2) provides for forward compatibility, @awwright, as long as you don't make any of the things that are added later mandatory. and either way, since RFC 7807 defined no such more specific mechanism, we cannot add one now without breaking things.

[awwright]

@dret Not to get this thread too off-topic, I filed #36 in response

[mnot]

Agree that #36 blocks this.

IF we do this, we'd need conventions for at least XML and JSON, I think -- which means that something more than just problem-pointer is necessary.

[mnot]

I started to rough this in. Working out the details made me realise this isn't a very good fit for a generic, standard member that's defined across all problem types, because:

• it's format-specific; we'll need to define e.g., json-pointer and xml-pointer for those formats; other formats will have to define their own
• it's specific to problem types that are about request state; it doesn't apply to problems that are about server-side state, for example
• it's specific to problems that have exactly one location in the request that triggers the issue

Instead, I think the example we have is sufficient, and we should close with no further action.

[mnot]

@sdatspun2 does that work for you?

[sdatspun2]

@mnot Sorry for lateness. The example may work... for now. However, I also agree with @darrelmiller. For a graceful evolution of this spec, we need figure out if requirements like the 4xx errors or multiple problems should be handled by defining a new media type or there could be some other way which is not as restricting (good and bad). I am not sure if the "best practices" document helps here, it will not be a standard. If new media type, I would think that it would need to evolve in future too so it has to be defined with that requirement in mind. Should there be a corresponding media type for problem type schema which can be referred from the existing media type?

We seem to be in a catch-22 here. We can't add it as a standard property in the specification because that would require a new media type and it has been asserted that we should not use examples to suggest how people might extend the specification.

Where does this leave us? Should we consider a complementary "best practices" document that suggests ways in which errors could be extended?

[mnot]

we need figure out if requirements like the 4xx errors or multiple problems should be handled by defining a new media type or there could be some other way which is not as restricting (good and bad).

Those are separate issues. Do we need to resolve them to ship this document (keeping in mind that we now have a path for future standard extensions to be defined)?

Should we consider a complementary "best practices" document that suggests ways in which errors could be extended?

I don't think that's necessary; what's important is that we build a community where those things can be discussed.