Draft: draft-ietf-httpapi-rfc7807bis

Commentary: Examples are using for consistency . Added an example for 207 and multiple problems . 
 this is a slightly confusing edit . the instance message is about the account not having enough funds . but it 's very unlikely and probably impractical that this message will be availble at the URI " /amount / value/50 " . it is more likely that the service keeps a message log somewhere along the lines of " /account//msgs / abc " and that when accessed , this log message will give you all the relevant details , probably including the " this costs 50 but you only have 30 " bit . 
 RFC 7807 says : problem . It may or may not yield further information if dereferenced . the current draft says : that identifies the specific occurrence of the problem . It may or may not yield further information if dereferenced . the current draft has a lot of additional text about relative URIs in that member , but not much regarding the meaning has been changed . do you think we need more text ? 
 URIs have no meaning , they are just identifiers . so at some level , this discussion is moot . but the way RFC 7807 works is that the instance URIs identifies the instance of the error . it could be anything . if it is referencable ( which it does n't have to be ) it most likely will reference a message in an error log that you can retrieve and inspect to learn more about the error instance . which is why i much prefer to use a URI that vaguely hints in that direction , rather than having one that vaguely hints in the wrong direction of suggesting that the URI itself has any inherent meaning . but it seems that by now we have established that this aspect of the spec seems to be harder to understand than we expected , so maybe some additional explanation is warranted . 
 i do n't find using instance URIs particularly helpful . imho , we should stick to the example of the original RFC , assuming that there is some persistent message storage , and showing how " instance " then could be used to link to that message that represents the problem instance . 
 iff we use this example we probably should n't use the fragment identifier separator . 
 Is this because application /  was not perhaps registered to support fragment identifier syntax or it is just a preference ? see my comment on the spec . { { RFC6901 , Section 6 } } says that a given media type needs to specify   as its fragment identifier syntax explicitly ( usually , in its registration { { RFC6838 } } ) . Does application / problem+json support    fragment identifier syntax ? 
 as discussed before , RFC 7807 had no intentions of pointing into a resource ; " instance " has an entirely different meaning . 
 Got it . Since  pointer could be represented either as a string or a URI fragment identifier , API developer could decide . Example is using the fragment identifier , but the description of the extension does not indicate any preference . 
 Example for multiple problems shows use of an extension called 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   . HTTP request validation errors are the most common and most frequent client side error in HTTP APIs . Opening this issue on suggestion of Although propertylocation is just as an example extension , having it in the specification gives it weight and authority . For something like this to be ( even if only as an extension to an example ) I think it needs to be thoroughly discussed in a separate issue first . 
 still agreeing with 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 . 
 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 . 
 Can this be closed ? 
 i think so since we have n't seen an actual proposal for this . 
 Hold on please . I have given example in Not sure if additional proposal was needed . 
 Note that adding a new member has potential issues ; see 
 We seem to be in a catch-22 here . We ca n'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 ? 
 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. ) have a standard meaning . If we ca n't do that without breaking backward compatibility , well then I do n't see a problem with a new media type . 
 my vote still goes to avoiding speculative examples . the built - in extension mechanism ( ) provides for forward compatibility , as long as you do n't make any of the things that are later mandatory . and either way , since RFC 7807 defined no such more specific mechanism , we can not add one now without breaking things . 
 Not to get this thread too off - topic , I filed in response 
 Agree that blocks this . IF we do this , we 'd need conventions for at least XML and  , I think -- which means that something more than just is necessary . 
 I started to rough this in . Working out the details made me realise this is n'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. , and for those formats ; other formats will have to define their own it 's specific to problem types that are about request state ; it does n'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 . 
 does that work for you ? 
 Sorry for lateness . The example may work ... for now . However , I also agree with 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 ca n'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 ? 
 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 ) ? I do n't think that 's necessary ; what 's important is that we build a community where those things can be discussed .
Note that this requires each of the subproblems to be similar enough
to use the same HTTP status code.  If they do not, the 207 (Multi-
Status) code RFC4918 could be used to encapsulate multiple status
messages.
In this case, the validation-error problem (identified by its type
URI) adds two extensions; "causes" is a JSON array that holds
multiple problems and "problem-pointer" is a JSON Pointer that points
to the source of problem in corresponding HTTP request.  Note that in
this example each of the subproblems are similar enough to use the
same HTTP status code.  If they do not, the 207 (Multi-Status) code
RFC4918 could be used to encapsulate multiple status messages as
shown in the example below.
The "instance" member is a JSON string containing a URI reference
that identifies the specific occurrence of the problem.  It may or
may not yield further information if dereferenced.
The "instance" member is a JSON string containing a URI reference
that identifies the specific occurrence of the problem.
When the "instance" URI is dereferenceable, the problem details
object can be fetched from it.  It might also return information
about the problem occurrence in other formats through use of
proactive content negotiation (see HTTP, Section 12.5.1).
When the "instance" URI is not dereferenceable, it serves as a unique
identifier for the problem occurrence that may be of significance to
the server, but is opaque to the client.
Similarly, the "Multi-Status" example defines two extensions -
"causes" and "problem-pointer".  Extensions like "problem-pointer"
are more appropriate to use for problems associated with client side
errors 4xx only.