Draft: draft-ietf-httpapi-rfc7807bis

Commentary: A couple of decision points to note : This mandates that title and detail contain ASCII strings . If folks feel unicode support is important , that could be done by also allowing binary , or using some encoding . This requires the problem type to define the SH type of any extensions . They also could be inferred , I suppose - but if there 's any JSON structure , that 'd get tricky . For . 
 Yes - my thinking is that an API will define which it uses . 
 yes , that works well from the perspective of API producers : they choose which way to go and then implement things accordingly . it 's less great from the perspective of consumers who oftentimes will consume more than one API to get their jobs done . now they need to jump back and forth and know what to expect based on which API they 're interacting with . in my mind , the more we can avoid consumers having to " know the API " and allow them to just work seamlessly across resources , the better . which is why i think even though it certainly is feasible to also represent problem details in a header field , it may be the better design overall to avoid adding the requirement to know where to look for problem details . 
 ( , which I think is blocked by this issue . ) I would call this specification " forward compatible " if we can add new features to it without interfering with existing compliant implementations . This is important so that standards can evolve to support new functionality , like proposed in . It does not appear to me that there 's any mechanism for forward compatibility , and this is noted : the problem type , it is not possible to define new " standard " members without defining a new media type . While the media type can be " extended " in some fashion , this is not the same as forward compatibility , because all extensions are by definition user extensions , so they can not be standardized . I.e. there is no way to define new " global " members . I think this is important to fix . I see a few options : ( 1 ) Note how the concept of " user " extensions has some amount of ambiguity . In order to know what a non - standard member means , you have to know who issued the Problem document . But there 's no standard way to encode this ! ( It does say the type is " effectively " a namespace for extensions , but this does n't seem like particularly authoritative language . ) Applications that are tightly coupled with a specific API may not have trouble consuming user extensions , but other user - agents ( e.g. spiders ) may have a problem deciphering them . Because of this , I think we could more rigorously specify the behavior without significant breakage " in the wild " . For example , specify that extension members must use a URI , and all other members have a standard definition . Or , choose some prefix that sorts high in ASCII , like or , to indicate standard " global " members . ( 2 ) If this still causes too much breakage , we could either reserve the member names that would cause breakage , or I would support minting a new media type . We could also consider defining a JSON - LD vocabulary . There 's likely a good way to encode the problem details that 's easily detectable as a document describing the error , and having a standardized form and properties , while also being easily extensible for specific types of problems / errors . 
 This has been discussed as part of a few other issues , but it 's good to separate it out into an explicit one . I think you 're in the ballpark here -- to allow new standard extensions ( i.e. , those not in the original spec and not explicitly nominated by the type in use ) , we have two choices : a naming convention that does n't conflict with existing usage ( e.g. , a prefix ) a new media type ( 1 ) is hard , because we do n't and ca n't know the extent of existing usage . However , we might be able to create a convention that 's extremely unlikely to conflict with existing usage , advertise it widely , and make sure there 's a transition period before it 's actually used . If we do all that , the risks could be low enough to be acceptable . ( 2 ) is certainly possible , but when we 've discussed this in the past , the concern has been that it would further fragment usage . There is a third option . We can define conventions that individual types opt into , saving them the work of defining the mechanism . For things like ( or whatever it becomes ) , that might be enough . 
 based on the IETF 113 discussion it looks like option ( 1 ) with a prefix that is n't too upsetting for  users is the best option going forward . it 's called " faking forward compatibility when you ignored it initially " and looks good enough to me . 
 How would clients know if a type has opted in or not ? And this enjoys some precedent from some other JSON media types ( JSON - LD ,   ) . Reserving a prefix seems to have also been deployed in e.g. HTTP cookies ( the double underscore prefix ) without too much breakage in the wild . Also , as I sort of hinted , it would be nice to add some stronger language about how to namespace or interpret extension members . Can we guarantee that two " balance " extensions are n't necessarily the same , if the " type " is different ? And what do we do if there is no type ? 
 If we choose a prefix , I think it needs to conform to the constraints that I just to -- That rules out things like . Of the two , Dictionary keys are more constrained - their first characters need to be lcalpha or . So how about ? 
 i am fairly open to anything since it 's nothing but an opaque thing that we will have to adhere to for future standard members . would it be ' " or ' - ' ? i may have a slight preference for the latter for readability . 
 Either one . is a bit weird IMO . Eg vs ( keep in mind that if does n't eventuate the possibilities open up quite a bit ) 
 See PR 
 Merging , with the expectation that we 'll discuss it on list and advertise this change to make sure we 're not clashing with anyone . Even if we do n't do the header field now , doing something compatible with SH dictionaries seems like a good idea so that it 's future - proof . 
 Should we define a header that can carry problem details ? E.g. , for the first example in the spec : a workable mapping might be to use to represent the top - level members of the object , like this : That drops any extensions that are not simple values , but I think that 's a reasonable tradeoff ... Would this be useful ? 
 Interesting idea ! Asking for some community feedback here : 
 I like the idea . Would it be a problem ( ) to name the header just ? 
 Unfortunately , structured fields do not work well with prose if it uses non - ASCII characters ... 
 " not well " or " not at all " , sounds a bit like the latter unless we 'd go through the effort of defining a specific mapping for non - ASCII characters . it would be an option to restrict values to ASCII for the field , but that would not be great in terms of i18n support . 
 " not well " in that we would need to allow byte sequences ( ) in addition to strings . 
 Can someone clarify what we are trying to solve with this suggestion ? 
 In the past , some have expressed a desire to convey problem details outside the body of the response , for whatever reason . This would facilitate that , in a limited fashion . 
 Could the example in the first post , be used together with ? 
 This seems like it would be a potential solution to the the topic of " warnings " that keeps coming back . I am assuming that returning header with a 2XX status code would be allowed . Although , I am a little terrified about the potential for abuse with that . 
 ping 
 I am curious about the use cases where error would be sent in header and rest of the goods would be sent in response body or in some cases errors are sent in response body and sometimes they are not . I wonder how the developer experience would be in consuming such an API . This could be explored to convey warnings though , I agree with 
 Thank you for the ping I agree with Yes , it is basically what we were trying to achieve with our I - D " " . Although in the I - D we named the header ( but that 's " just naming things " ) - and we were trying to return the warning information in the body . Which brings us to the matter of developer experience , that was writing about . TBH , it still feels weird to have problem details in the body and warnings in the header . Should n't both be in the body or both in a header ? But maybe that is just my own stubbornness . Anyway - it 's very confusing when you can return data in either the body or in a header or - god forbid - in both at the same time . Who knows maybe someone will even put different content in each . Which is probably what was thinking about when he 's thinking about abuse . ... I 've been thinking about this the whole day and I 've come to the conclusion that there is probably only one solution .   in the body .   in a header This way problem details are being transmitted the same way the original RFC proposed . There is no confusion , because problem details can be in the body or not . If there is a warning it can be transmitted as a header , thus keeping the integrity of the original RFC . There 's probably one caveat . In my mind there 's always the use case where multiple warnings are being returned . This could lead to problems when the value gets too big for a server to handle . Which is why I 'd love to have the warnings in the body . One can simply return more data in the body . Also , having one " severity level of information " in the body and another one on a header feels weird to me , maybe this is a compromise I 'll have to make . All the other options do n't seem feasible , due to the side effects stated above . do you have insights into the use cases for having problem details in the header ? The only reason that comes to my mind is when a " 204 - No Content " response is being returned . Then it would n't seem right to have problem details being returned as the only content . 
 liking reasoning here which could mean for RFC7807bis to potentially subsume the draft ( probably renaming the header field but using the same general idea ) . or we could stay the course , stick with RFC 7807 's model of content - only , and possibly revive and better align the http - warning draft , potentially even adopting the name suggestion made by i kind of like the second option better so that RFC7807bis stays lean and mean without adding too many new things . 
 If we think that this is going to be done / get used , we should probably do it now , to avoid the overhead of opening another spec . That said , I do n't see a strong response -- I 'm happy to leave this floating as an idea that we might get to one day if demand eventuates . 
 What if I want to transmit multiple problems — for example , what if I 'm operating a gateway and I want to add a problem header without changing the semantics of an existing upstream one ? Should n't the fields be delimited with a semicolon ? 
 I think warnings and errors are distinctly different and thus should be treated differently . In most programming languages , errors are conveyed by having their own keywords ( or ) and types ( or ) , while warnings are usually delegated to logs . In the terminal , is separate from and while you 'd expect a CLI application to continue executing through the occurrence of warnings , you 'd expect a non - zero exit if it were to encounter an error . For this reason , I think the treatment of errors and warnings warrants a different behavior in HTTP as well . Delegating warnings to a header ; allowing the app to continue working – while allowing errors to take over the entire response and thus stopping the application from working – feels both natural and right to me . What I do think warnings and errors share , though , is structure ; which is why I 'm supportive of a suggested header conveying the same data and  as that of RFC 7807 . And as writes , a header is even able to convey multiple problems in a simpler and more ergonomic way than what is possible in the HTTP body , by separating each problem occurrence ( i.e. warning ) with a comma ( with each field within a problem occurrence separated by a semicolon ) . While I do n't think it 's very important to bake the header into the same spec as rfc7807bis , I do see the benefit of maintaining them in synchrony to avoid feature drift and ( worst case ) incompatibilities . So if was to come down to a vote , I would give a +1 to roll the header into rfc7807bis . 
 the problem object can only serialise one problem , I think the same would apply here . 
 Hey I 'd like to challenge you a bit on your statement . Sure , at first it seems that errors and warnings are handled differently since they are separated from each other by different " logfiles " . But the actual process of logging the error or warning is the same . You send an ( error or warning ) string to a file . But I can relate to what you 're trying to say . What you are logging can be totally different . Most often errors come with a stack trace , giving a more detailed look into the " state of the machine " at the time . Thus when looking at an error file you 'd expect different types of log entries , then in a file that warnings have been written to . Anyhow , I think we 're both trying to achieve the same thing here . As I wrote earlier , I 'd be happy to have warnings in a header field . Unfortunately , the challenge I see is still there , when returning warnings one would probably want to return more data , than with an error , thus resulting in messages that could get too large . If this is something everyone thinks is negligible then let 's go for the header field . 
 I would expect if one problem document can serialize one problem , then one Problem header would serialize one problem . It 's not obvious to me that this would " bubble up " to the entire HTTP message . Also I would expect HTTP semantics to apply , if I append a Problem header , that it wo n't change the meaning of existing headers ( or at least , I would expect this to be a detectable error or ambiguity ) . 
 I just came across this discussion by incident . I 'm a bit late for the party ... so please ignore me if you think the following makes no sense : I do n't really see the point in having problems / warnings in a header field . Is n't a problem a " business problem " ? Something like " out - of - credit " . It is not some meta data but it is something essential that is relevant to " the business " . The same is the case for warnings . To me this is an essential part of the response , so why would I want to add this to a Header - Field ? It should be part of the body oft the response . It is still possible to define some kind of standard structure for this kind of stuff and then you embed that into your response ( as draft - cedik - http - warning-02 suggests ) . 
 I 'm not sure if there 's a specific use defined , but I would use it similar to 4xx errors . If there 's no specific 4xx code for the error , this enables you to use a Problem header field with a 400 Client Error to make your specific class of error more machine - readable . Whereas normally , 400 requires human intervention because it could mean any error . 
 i agree in principle , but i 'd argue that you could make the specific error equally machine - readable by using a body with a problem report . where a header may be useful is when you want your API to generate human - readable error responses ( in HTML ) but still want a machine readable version for machine clients . there would be other patterns to accomplish the same goal , but i think that 's a line of reasoning you could follow . 
 I do n't really see why one would need both things at the same time ( but maybe my view is too limited ) . Either you request a HTML page and then you also expect a HTML response in case of an error . OR you add " application / problems+json " in addition to some " application /  " type to the accept header and you get the machine - readable response- Assuming your request a HTML file and it is returned with the header in question : How would you access these header fields ? If you load a page with a browser you ca n't afterwards access the HTTP - Headers of this page in  ( I had too look that up here : ) . Or you load the page with javascript but then why would you request a HTML ? It would be possible of course but why ? Of course : If browsers started to support this header field natively then maybe ... 
 I would expect a header along with an HTML document for the same reason I would expect a server to respond with a 4xx code ( instead of a generic 400 one ) . It provides more information about the nature of the error to the user agent . That is , the Problem header is probably intended for use by the user agent itself — not the webpage . ( Although I agree , a webpage should be able to access the response headers that it was delivered with , except possibly Set - Cookie . ) 
 Coming back to this , it seems like there 's some support for adding this , but it 's not especially strong . I ca n't see too many risks of including it in the spec ( obvious worst case : it does n't get used ) . That 's not enough to justify including it , of course . perhaps a consensus call on list is in order ? 
 Sure , a consensus call is fine . But could you write a summary of this issue and post to the list ? 
 I like it a lot . Error messages are a serious problem point in most HTTP based APIs . Everybody rolls their own error spec , with slightly different semantics . It 's good to have them specced consistently and sanely . The semantics used in the spec are very sound . There 's : a unique computer - readable ID ( type ) , a human - readable and translated description of the generic problem , a specific human - readable and translated description of the specific problem with parameters , and custom computer - readable parameters for the values of this specific error . This is great . I also love that you say that " detail " shall not be parsed , but custom values ( " extensions " ) be used . I would just improve 2 aspects : Add " debug " and " stack " as explicit additional fields . It 's great that you specifically mandate that " detail " shall not contain debugging info . That 's wise to define , because a field called " detail " is bound to be used for that . Unfortunately , most devs do not read specs , so if you have a field called " detail " , I 'm certain that devs are going to put stack traces in there . To avoid that urge , I would recommend to add two explicit fields " debug " and " stack " . Both optional of course . But they should be two separate fields , because the stack is well - defined , and " debug " can be a dump of internal variables or anything else useful for debugging . Be more tight in the definitions . Please mandate that the title and detail fields are in fact translated on the server side . The client can not realistically do it , because the server can add new error conditions at any time , plus the business of including parameters in the user message . It 's important that there is clarity about who is responsible for the translation of the error messages , and that this aspect is not left vague . So , I would define clearly : If there is a translation happening at all , then the server is translating the human - readable message , not the client . Other than these two simple changes : I like the spec a lot , and it 's very much needed . Thanks for your push for it ! 
 This seems like a fairly simple way to manage this . I 'm most concerned about there being only one way to learn about a problem , which this directly challenges . Including the problem report in the body of a 4xx response is unambiguous , whereas this means that you need to look in two places .
This document defines a "problem detail" to carry machine-readable
details of errors in a HTTP response to avoid the need to define new
error response formats for HTTP APIs.
This document defines a "problem detail" to carry machine-readable
details of errors in HTTP response content and/or fields to avoid the
need to define new error response formats for HTTP APIs.
To address that shortcoming, this specification defines simple JSON
RFC8259 and XML XML document formats to describe the specifics of
problem(s) encountered - "problem details".
To address that shortcoming, this specification defines simple JSON
RFC8259 and XML XML document formats and a HTTP field to describe the
specifics of problem(s) encountered - "problem details".
This document uses the following terminology from STRUCTURED-FIELDS
to specify syntax and parsing: Dictionary, String, and Integer.
When creating extensions, problem type authors should choose their
names carefully.  To be used in the XML format (see xml-syntax), they
will need to conform to the Name rule in Section 2.3 of XML.  To be
used in the HTTP field (see field), they will need to conform to the
Dictionary key syntax defined in Section 3.2 of STRUCTURED-FIELDS.
Problem type authors that wish their extensions to be usable in the
Problem HTTP field (see field) will also need to define the
Structured Type(s) that their values are mapped to.
Some problems might best be conveyed in a HTTP header or trailer
field, rather than in the message content.  For example, when a
problem does not prevent a successful response from being generated,
or when the problem's details are useful to software that does not
inspect the response content.
The title and detail values MUST NOT be serialized in the Problem
field if they contain characters that are not allowed by String; see
Section 3.3.3 of STRUCTURED-FIELDS.  Practically, this has the effect
of limiting them to ASCII strings.
An extension member (see extension) MAY occur in the Problem field if
its name is compatible with the syntax of Dictionary keys (see
Section 3.2 of STRUCTURED-FIELDS) and if the defining problem type
specifies a Structured Type to serialize the value into.
Please update the "application/problem+json" and "application/
problem+xml" registrations in the Internet media types registry
RFC6838. to refer to this document.
Please create the HTTP Problem Types Registry, as specified in
registry, and populate it with "about:blank" as per blank.
Please update the "application/problem+json" and "application/
problem+xml" registrations in the "Media Types" registry to refer to
this document.
Please create the "HTTP Problem Types Registry" as specified in
registry, and populate it with "about:blank" as per blank.