Draft: draft-ietf-httpapi-rfc7807bis

Commentary: done ; see change . P.S. GitHub lets you make suggestions using the little + /- icon in the inline comment UX :) 
 Pulling this conversation out of : 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 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 . 
 We ( well , mostly have made some good progress on the other issues raised out of but we have n't looked at this one yet . As strawman to get this moving , how about : we register a URN namespace i d , and we recommend that non - dereferenceable URIs should be URNs using that , namespaced with an appropriate domain and raw type i d , for example : . 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 do n't have examples , but I suspect there are other standards elsewhere that would appreciate having a problem i d namespace for URNs as well . I do n'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 : 
 We penciled in the URI prefix for registered types as " " in , 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 ) . 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 or something similar , as per . 
 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 . 
 : +1 : exactly I think is relevant in that it would be helpful to everybody if we can follow our own recommendations in our own problem i d 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 above ) , whereas most orgs minting problem types probably wo n't have one and wo n'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 . 
 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 URI . 
 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 . 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 .
Non-resolvable URIs ought not be used when there is some future
possibility that it might become desireable to do so.  For example,
if the URI above were used in an API and later a tool was adopted
that resolves type URIs to discover information about the error,
taking advantage of that capability would require switching to a
resolvable URI, thereby creating a new identity for the problem type
and thus introducing a breaking change.