Make a clear recommendation for the 'type' to use when not linking to a documentation URL

[pimterry]

Pulling this conversation out of #11:

It's clear that there's demand for error codes scoped to the API, without creating documentation pages for each code and linking to them in the type field. There are many ways that implementers could do this, from linking to non-existent URLs to URNs to tags URIs, etc.

It would be useful if the specification included examples of this, and made a clear recommendation for this case.

[pimterry]

We (well, mostly @mnot) have made some good progress on the other issues raised out of #11 but we haven't looked at this one yet.

As strawman to get this moving, how about: we register a problem URN namespace id, and we recommend that non-dereferenceable URIs should be URNs using that, namespaced with an appropriate domain and raw type id, for example: urn:problem:example.com:out-of-credit.

Would that work? It would give us a clear solution to recommend, which is explicit but easy to read, with minimal extra complexity or overhead for implementers (imo).

I don't have examples, but I suspect there are other standards elsewhere that would appreciate having a problem id namespace for URNs as well.

I don't love using a domain for namespacing a non-locator, but I think some namespacing is preferable, and I'm not sure what other namespaces would be suitable. Alternatives very welcome :smile:

[mnot]

We penciled in the URI prefix for registered types as "https://iana.org/assignments/http-problem-types#" in #7, but that was not finalised.

I think registering one or more problems as exemplars is a good path forward for this and other issues (e.g., as discussed in #6). We need to be very careful to set a good example in them, which means we need good candidates; I'm thinking 'JSON Validation Error' and 'XML Validation Error' might be appropriate (perhaps along with corresponding wellformedness errors).

If we choose a urn, I suspect there will be considerable pressure to use urn:ietf:params:http:problem: or something similar, as per RFC3553.

[dret]

On 2021-08-31 04:40, Mark Nottingham wrote:

If we choose a urn, I suspect there will be considerable pressure to use |urn:ietf:params:http:problem:| or something similar, as per RFC3553 https://www.rfc-editor.org/rfc/rfc3553.html.

my understanding of the "urn:ietf:params" namespace is that it is meant to be used for parameters managed/defined by IETF specs.

i think the original's suggestion intent was to have a "safe prefix" for a namespace which then would be "unmanaged" with some conventions around that, such as using domains names.

i think the idea of giving examples (and even a suggested namespace along with conventions for using it) is a good one. that way we can clearly support both scenarios:

• if you're planning on making documentation available, use a resolvable URI but keep in mind that this best should be managed in a way so that it works for a good number of years.

• if you're planning on just identifying problem types, use a non-resolvable URI, and here's a recipe for doing it.

[pimterry]

i think the original's suggestion intent was to have a "safe prefix" for a namespace which then would be "unmanaged" with some conventions around that, such as using domains names.

• if you're planning on making documentation available, use a resolvable URI but keep in mind that this best should be managed in a way so that it works for a good number of years.
• if you're planning on just identifying problem types, use a non-resolvable URI, and here's a recipe for doing it.

:+1: exactly

I think #7 is relevant in that it would be helpful to everybody if we can follow our own recommendations in our own problem id registry, but it's otherwise independent.

[dret]

On 2021-08-31 09:52, Tim Perry wrote:

I think #7 https://github.com/ietf-wg-httpapi/rfc7807bis/issues/7 is relevant in that it would be helpful to everybody if we can follow our own recommendations in our own problem id registry, but it's otherwise independent.

the difficulty may be that IETF has an institutional approach for managing parameters (urn:ietf:params:http-problems mentioned by @mnot above), whereas most orgs minting problem types probably won't have one and won't create one. which may lead to us to saying three things about what kind of URI to use:

• check out common problem types registered under urn:ietf:params:http-problems and consider reusing one if it fits.
• use URIs when creating dereferencable problem type identifiers.
• when using non-dereferencable problem type identifiers be clear about that by using non-dereferencable URIs, and here's an URN-based recipe how to do that.

[pimterry]

the difficulty may be that IETF has an institutional approach for managing parameters (urn:ietf:params:http-problems mentioned by @mnot above), whereas most orgs minting problem types probably won't have one and won't create one. which may lead to us to saying three things about what kind of URI to use:

• check out common problem types registered under urn:ietf:params:http-problems and consider reusing one if it fits.
  • use URIs when creating dereferencable problem type identifiers.
  • when using non-dereferencable problem type identifiers be clear about that by using non-dereferencable URIs, and here's an URN-based recipe how to do that.

Ah, I see, ok. Yes, that makes sense, and given that the 3 part recommendation seems reasonable to me.

[mnot]

my understanding of the "urn:ietf:params" namespace is that it is meant to be used for parameters managed/defined by IETF specs.

No, it's for parameter name spaces managed by IETF documents -- which this would be.

We could also give an example that uses a tag URI.

[dret]

On 2021-09-01 03:37, Mark Nottingham wrote:

my understanding of the "urn:ietf:params" namespace is that it is meant
to be used for parameters managed/defined by IETF specs.

No, it's for parameter name spaces managed by IETF documents -- which this would be.

that's what i wanted to say. so these URIs/examples would just cover the common problem types that would be managed by the spec.

We could also give an example that uses a |tag| URI.

which then would be for those other types that people/orgs are minting and where they say these are not resolvable, right? i think for those terry proposed a URN namespace instead of tag URIs, but either way it simply would help to state the use case ("your own types, not intended to be resolvable") and provide a recipe ("here's one way to do it").

the main point seems to be: the spec should mention both "common types" which may even get a registry, and "private types" which probably are using a different namespace, and we could suggest one pattern for doing that.