3.1.1. The "type" member is a JSON string containing a URI reference RFC3986 <del> that identifies the problem type. </del>  <del> This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML HTML5).  When this member is not present, its value is assumed to be </del>  "about:blank".  When "type" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using relative URIs can cause confusion, and they might not be handled <del> correctly by all implementations.  For example, if the two resources "https://api.example.org/foo/bar/123" and "https://api.example.org/ widget/456" both respond with a "type" equal to the relative URI reference "example-problem", when resolved they will identify different resources ("https://api.example.org/foo/bar/example- problem" and "https://api.example.org/widget/example-problem" respectively).  As a result, it is RECOMMENDED that absolute URIs be used in "type" when possible, and that when relative URIs are used, they include the full path (e.g., "/types/123"). Consumers MUST use the "type" URI (after resolution, if necessary) as the primary identifier for the problem type.  Consumers SHOULD NOT automatically dereference the type URI. </del>  3.1.2. When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using relative URIs can cause confusion, and they might not be handled <del> correctly by all implementations.  For example, if the two resources "https://api.example.org/foo/bar/123" and "https://api.example.org/ widget/456" both respond with an "instance" equal to the relative URI reference "example-instance", when resolved they will identify different resources ("https://api.example.org/foo/bar/example- instance" and "https://api.example.org/widget/example-instance" respectively).  As a result, it is RECOMMENDED that absolute URIs be used in "instance" when possible, and that when relative URIs are used, they include the full path (e.g., "/instances/123"). </del>  3.2.

Pulling this conversation out of : The current spec allows any type URLs to be used, and there's no strong requirement that they link to documentation, it's just encouraged. As an API client, it can be useful to be able to automatically find human-readable documentation relevant to an error response. Right now, the only way to do that is to dereference every type URL to see if it goes to a documentation resource, but a) that's discouraged by the spec (type URIs should not be dereferenced automatically) and b) it's not very efficient for anybody involved. As an example, Zolando's specify that: All their API responses use absolute path types to deal with this, like , which intentionally go nowhere. This is allowed by our current spec, but makes life difficult for those of us who want to automatically find documentation from arbitrary problem detail responses. It would be useful to provide an explicit way to link to documentation in these cases, or to make it clear that no documentation is available.
With identification using URIs, you never quite know if it is a document or just a reference to a concept. Any person that followed httpRange-14 back in the days knows that this is hard. That said, the scenarios are multiple: Identification only relies on expanding a uri to its full form (from a basue uri for any uri), and checking it against a known value can i learn anything from it, which is a "follow your nose" first principle: click on it, see if anything comes out If you were to add a "documentation" uri, i have no more guarantee that anything usefull will come out of it rather than following my nose to the original type, so I'm not sure Im gaining a lot from a predictability perspective. If the main operator is human, then a documentation URI would only make sense because it overrides the main URI, which would only be done if said URI is not in control of the operator that published said URI. This seems unlikely to me, but I could see a scenario where you want, on your own API, to provide your own documentation for that above and beyond from the one that would be provided by the provider of that error. I'm not sure what i think about that capacity, to say that "in our realm, we don't do things the way they said, we got our own". It's an open question for me. If the main operator is a machine, then just a URI seems insufficient, especially as the override i mentioned above would be needed per type of automate-able documentation one could retrieve.
In that case, I wonder if a Link header - with maybe? - would be a better way of achieving that? That way the actual problem payload doesn't change just because some server wants to indicate that human-readable documentation about the problem exists somewhere different to the provided URI.
jumping in to hopefully make some progress with this: "automatically" following type links (as mentioned by NAME isn't a great idea, since this may cause the well-known problem of overwhelming the server of the type URI. that's why RFC 7807 says that "Consumers SHOULD NOT automatically dereference the type URI." instead of adding a specific "hint", we could add language saying that if you want your type URIs not to be dereferencable, just create them that way, for example by using URNs (or similar URI schemes). that way, we could one the one had provide guidance for those who want to create dereferencable URIs (make them absolute) and for those not wanting dereferencable URIs (do not use relative URIs but instead use URI schemes that have no associated dereferencing mechanism, such as URN URIs).
that way, we could one the one had provide guidance for those who want to create dereferencable URIs (make them absolute) and for those not wanting dereferencable URIs (do not use relative URIs but instead use URI schemes that have no associated dereferencing mechanism, such as URN URIs). So, what if I create a problem type that I originally intend not to be deref'd, but down the road I need it to be? It seems to me that the harm in always using dereferenceable URLs is pretty minimal/manageable -- People who try will get 404's (for HTTP URLs) Domain name ownership is a thing (for schemes based on DNS) So an alternative would be to recommend using HTTPS URLs in most cases, with a proviso that sometimes they won't be resolvable (something a person can discover at their convenience), and that for standard / widely-used codes, a HTTP URL that's stable (possibly provided by IANA, as per ) is wise. Related to .
We can recommend this, but it seems likely that most problem types will still intentionally not be resolvable, unless it's a hard requirement. The Zalando style guide specifically encourages that it should do so, and discussion elsewhere - it seems that API developers (for some good reasons, e.g. uncoupling type ids from doc URLs) want to use unresolveable type URLs, independent of their documentation URLs. As a tool author, that means I'm going to have to automatically dereference every problem details type URL every time I receive such a response. That's not great for anybody. I want to automatically find a working URL for problem documentation, every time a problem is received. In my case, I'm working on an HTTP debugger where that's especially relevant, but you can imagine many other use cases, e.g. in low-level libraries or clients, perhaps an HTTP library that throws clear friendly exceptions to help with debugging every time it receives a problem details response, something like: The problem is in the last line. If that goes to a 404 (likely to happen in many cases) it's a very poor user experience for the end developer looking at their error logs, who's just been told that it's working documentation. Tools/libraries will reasonably want to avoid that experience as much as possible - the only current way to do so is to dereference every problem URL when it's received, or to never try to link to documentation at all. If this is a use case we just don't want to support in this RFC then that's not totally unreasonable, and we could just close this. It seems like we're very close to machine-discoverable problem documentation here though, and personally I'd find that very useful. This is another separate good reason why imo it'd be useful to have a explicit and independent way to link to problem details documentation from a response (e.g. a link header, a separate field, etc etc)
Here's an interesting detail. If there was some way to determine that a problem URI was resolvable, and it resolves to a redirect then what does that mean? I ask this because the comment I was originally going to make was about dead documentation links. I could make a problem URI today that is resolvable, but there's no guarantee that it will still be resolvable in the future. Or, worse, it might just resolve to the wrong thing. And that then got me thinking about other ways that URIs can resolve to the wrong things, and redirects seems a particularly awkward one. I would assume that it doesn't mean anything, and that the URI as written in the payload is the one to use. But equally, I can see an argument that two different URIs that both resolve as redirects to the same thing could be considered as the same problem, and that just makes life awkward.
Performing HTTP redirection from the URI to documentation is actually , since what's used in is supposed to be a stable identifier, while the URI of a documentation site may be generated by a CMS and thus probably can't be considered stable. I've never even considered that a URI comparison implementation could perform an HTTP request against the two URIs and see whether they, after HTTP redirection and whatnot, resolve to the same URI. Using resolvable URIs that perform HTTP redirection as identifiers is common. The whole of does it, for instance: redirects to . The former is the canonical identifier, the latter is the documentation about the identifier.
Whether or not it resolves to a redirect doesn't change the problem identified by the type URI. If folks believe otherwise, please open a separate issue. NAME I see what you're saying regarding tool user experience. I'm not against this, I could see us adding a member with a boolean value whose semantic is 'here's a hint that the type URI is resolvable'; I could also see us adding a member with a separate URI for documentation. However, two things come to mind: Even if the problem says that the URL is resolvable, it still might not be (e.g., network failure, server-side issue, etc.). Some problems are going to omit this signal even when the URL is resolvable -- either because they don't know about the signal, or they don't care. Both of these reduce the quality of the information that the signal conveys. What I think we need to establish is whether it still conveys enough information to be worth the extra effort and complication. If we don't have this sort of signal, I think a tool such as the one you're talking about will need to present it as something like: Alternatively, you could attempt to resolve the URI and then cache the result, avoiding the need to make a request for every problem instance. To facilitate that, it might be interesting to put some bounds on how cacheable these type URIs are... Either way, we should qualify the 'automatically' prohibition against resolving the URI to make it applicable to runtime resolution, not debug time. Thoughts?  I find that an often under-appreciated aspect of APIs is the cognitive load they place upon users; if there are too many options, they're less likely to use what's available well.
One other aspect of this that we haven't discussed: if we're talking about adding a new member that's valid and standard across all problem objects, it violates this statement in 7807: So if we decide that this is a must-have, we'll need to either define a new media type for problem types, or convince ourselves that defining such an extension won't break currently deployed extensions (without being able to know their breadth).
Discussed in 111: default resolvable is good. Not a strong motivation for a 'doesn't resolve' flag; close with no action (except perhaps prose).
Sounds good to me. If we can strengthen the spec from gentle encouragement to "if the type is dereferenceable, it SHOULD resolve to documentation" (or similar) and qualify the "Consumers SHOULD NOT automatically dereference the type URI" text as , then my use case should work reliably with no extra fields required, which would be great. This then ties into & : we should give a clear recommendation for an alternative, for those who do want explicitly non-resolvable types. Does all this apply the same to ? That currently doesn't state a position on this at all: "It may or may not yield further information if dereferenced"
wouldn't that be odd? the type URI probably mostly will be used for comparing to some known type URIs. the instance URI on the other hand probably most often will provide access to info analyzing the specific reasons for the problem, no?
It's just that the same ambiguity applies: is intended as a link to a resource the receiver should visit for more information about that specific transaction, or intended only as an opaque identifier? It's quite plausible that the situation isn't the same as , and that's OK. It's not really as important for tooling AFAIK (I imagine tools are all more likely to be interested in linking to human-readable documentation than the failing resource itself, which could be anything) and I don't have a strong opinion either way. If we do think both should be treated similarly (i.e. both should be resolvable by default) then that's neat and we can use consistent recommendations throughout. If not then that's fine too - we just need to make it clear that they're different (and if this is the case, I think the current text does that OK). Either way I think an answer for as well as would be nice, so that it's clear what to do if you want either to be explicitly not resolvable, but that's just offering an optional suggestion, not a constraint.
See proposal in - thoughts?
Good improvement, for me, thanks!

3.1.1. The "type" member is a JSON string containing a URI reference RFC3986  <ins> that identifies the problem type.  Consumers MUST use the "type" URI (after resolution, if necessary) as the primary identifier for the problem type. </ins>  <ins> When this member is not present, its value is assumed to be </ins> "about:blank". <ins> If the type URI is a locator (e.g., those with a "http" or "https" scheme), dereferencing it SHOULD provide human-readable documentation for the problem type (e.g., using HTML HTML5).  However, consumers SHOULD NOT automatically dereference the type URI, unless they do so in the course of providing information to developers (e.g., when a debugging tool is in use). </ins> When "type" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using relative URIs can cause confusion, and they might not be handled  <ins> correctly by all implementations. For example, if the two resources "https://api.example.org/foo/ bar/123" and "https://api.example.org/widget/456" both respond with a "type" equal to the relative URI reference "example-problem", when resolved they will identify different resources ("https://api.example.org/foo/bar/example-problem" and "https://api.example.org/widget/example-problem" respectively).  As a result, it is RECOMMENDED that absolute URIs be used in "type" when possible, and that when relative URIs are used, they include the full path (e.g., "/types/123"). </ins> 3.1.2. When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using relative URIs can cause confusion, and they might not be handled  <ins> correctly by all implementations. For example, if the two resources "https://api.example.org/foo/ bar/123" and "https://api.example.org/widget/456" both respond with an "instance" equal to the relative URI reference "example-instance", when resolved they will identify different resources ("https://api.example.org/foo/bar/example-instance" and "https://api.example.org/widget/example-instance" respectively).  As a result, it is RECOMMENDED that absolute URIs be used in "instance" when possible, and that when relative URIs are used, they include the full path (e.g., "/instances/123"). </ins> 3.2.


3.1. <del> A problem details object can have the following members: </del>  3.1.1.

From URL : JSON objects with a null "type" are syntactically correct, but there is no information on how it should be handled. { "type": null, "status": 404, "title": "Not Found" } It makes sense to treat null as an alias of "about:blank" and that's how I think it should be documented.
Note that the errata above is only . My .02 -- if is , it's invalid, not "syntactically correct"; it's specified to be a string, and if someone assumes that has semantics, that's not currently specified behaviour. So the real question here is whether the default of is assumed when the value is invalid, or whether some other error handling comes into play. I think the safest thing to do would not be to assume that implies -- i.e., no change to the spec.
Since this is a specification of a format for error messages, I believe it is important that the processing of the error message is clear and lenient so the processing itself does not cause errors, possibly shrouding the initial error that caused the response in the first place. I therefore think the specification should be explicit that all erroneous values (such as , , , etc.) should be ignored and treated as the default value of each member, which for equals to , but for other members equal to an empty string(?).
I think I agree; changing issue title.

3.1.  <ins> Problem detail objects can have the following members.  If the type of a member's value does not match the specified type, the member MUST be ignored - i.e., processing will continue as if the member had not been present. </ins> 3.1.1.


The ability to convey problem-specific extensions allows more than one problem to be conveyed.  For example: <del> 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. </del>  3.1. 3.1.5. The "instance" member is a JSON string containing a URI reference <del> that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced. </del>  When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using extensions - "balance" and "accounts" to convey additional, problem- specific information.  Clients consuming problem details MUST ignore any such extensions that they don't recognize; this allows problem types to evolve and include additional information in the future.

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/12345/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 doesn'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 don'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 shouldn't use the fragment identifier separator.
NAME Is this because application/problem+json 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 JSON Pointer as its fragment identifier syntax explicitly (usually, in its registration {{RFC6838}}). Does application/problem+json support JSON Pointer's 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 JSON 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 added 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 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 NAME >Although propertylocation 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.
still agreeing with NAME 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 haven't seen an actual proposal for this.
Hold on please. I have given example in URL Not sure if additional proposal was needed.
Note that adding a new member has potential issues; see URL
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?
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 can't do that without breaking backward compatibility, well then I don't see a problem with a new media type.
my vote still goes to avoiding speculative examples. the built-in extension mechanism (URL) provides for forward compatibility, NAME 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.
NAME 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 JSON, 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 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., and 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.
NAME does that work for you?
NAME Sorry for lateness. The example may work... for now. However, I also agree with NAME 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?
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 don't think that's necessary; what's important is that we build a community where those things can be discussed.

The ability to convey problem-specific extensions allows more than one problem to be conveyed.  For example:  <ins> 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. </ins> 3.1. 3.1.5. The "instance" member is a JSON string containing a URI reference  <ins> 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. </ins> When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using extensions - "balance" and "accounts" to convey additional, problem- specific information. <ins> 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. </ins> Clients consuming problem details MUST ignore any such extensions that they don't recognize; this allows problem types to evolve and include additional information in the future.


that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.  When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using relative URIs can cause confusion, and they might not be handled

As discussed in URL, this PR expands on the dereferenceability of to clarify what the URI is expected to return, which hopefully also clarify the intended use of .
Merging, might tweak a bit further in situ. Thanks!

that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced. <ins> When the "instance" URI is dereferenceable it can return the same problem response that was returned to the client which generated the problem originally.  It might also return more information about the problem occurrence in other formats (e.g., using 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. </ins> When "instance" contains a relative URI, it is resolved relative to the document's base URI, as per RFC3986, Section 5.  However, using relative URIs can cause confusion, and they might not be handled


"problem-pointer" to locate the problem within the request's content using a JSON Pointer RFC6901. <del> When the problems to be conveyed cannot share the same HTTP status code, the 207 (Multi-Status) code RFC4918 could be used to encapsulate multiple status messages as shown in the example below. </del>  3.1.

As discussed on-issue.
Looks good to merge.
Sometimes an API will want to report more than one problem in a response. 7807 explains that this can be done in extensions, but does not natively allow multiple problems to be conveyed, because there was concern that doing so would make it too easy to contradict the semantics of the status code. Since publication, developers have still wanted a generic solution to this. A few possible directions we could go on: Do nothing Improve the documentation regarding how to handle multiple problems in extensions Introduce a way to natively convey multiple problems, as long as they share the same status code semantics Something else?
I'm somewhat curious how often multiple different problems really happen, as opposed to multiple different facets of the same problem. By "multiple different facets of the same problem", I'm meaning things like request validation failures. A request might be invalid because of multiple different fields in the incoming JSON(/whatever content type is being used). But the overall problem is still "Validation Failed". It's just that it failed for several reasons. The real multiple problems would, in my mind at least, be something like: The incoming request was invalid (So a "Validation Failed" problem with a status of 400/422) And you don't have permission to do this (So a "Permission Denied" problem with a status of 403) And the resource doesn't exist (So a "Not Found" problem with a status of 404) The "multiple facets" case is relatively simple to support. Indeed, I'm sure the wider community have a myriad of different ways to do it already, but obviously a standard way to achieve it would be better. The "multiple problems" case is much harder, simply because of the different status codes that can come up. But my (potentially naive) suspicion is that it's also less useful.
I hope it's useful, here is the scenario of what we currently do (it's a work in progress). We currently retrieve various problem documents from various api calls that are done in a scatter/gather scenario, unbeknownst to the client. We aggregate those potential multiple problems: if they're all the same type / status, we reuse this and agrgregate the details. if they're not of the same type / status, we extract a response status (see below) and set the type to an "aggregate", and add a array of problem documents to provide details of each of the errors encountered during this call The status code in the case of an aggregate is set according to those rules: if all status codes are the same, use this status code if status codes are not the same but in the same 100th, set it to 400 or 500 if it's spread across, use a 500 It's not ideal but it allows us to communicate to the client why their request failed, with information about each dataset that may have rejected a request.
NAME that's an interesting pattern. I could see recommending that in the spec, and advising problem definitions to think carefully about accommodating multiple instances of their details...
I agree with the facets ideas. And I would go further by asking to provide a format for validation errors.
I agree with this. I find it hard to imagine that clients will actually attempt to resolve all problems in a multi-status response before retrying a request because the implementation seems like it would be overly complicated. NAME in practice, do your clients attempt to resolve multiple the problems or are the problems merely logged? Option 1 seems most pragmatic to me. I.e. explain that a problem type can use extensions to define an array of subproblems with examples. Then explain that if the problems are not subproblems of a broader category, the server should choose the most critical problem. If the server doesn't choose the most critical problem, then we will likely have to provide a way to order/prioritize problems in the media type to guide the client. For example, if a server responds with both the and error types, the client will have to understand that it's a waste of time to fix the validation error because the server is out of space. This still permits a client to fix multiple problems iteratively by retrying the request after each problem has been fixed.
NAME in practice, when there are multiple problems, it comes to a human to analyse. That analysis can be done iwth raw text, or with structured data. People do structured data all the time, and if you don't have an answer they'll build their own. Now, the rules we use is to allow a simple automated system to take care of the cases where the most specific issues happen (say, two gateways are timing out, it's a timeout, we merge towards a specific status code, automated clietns take care of it). In the cases where they're not, the lack of standard way of communicating a common scenario leads to one of those less than ideal scenarios: try not to step on the spec's turf, and create your own schema (implementation cost reduction through network effect nullified, no way to generiically notify operators as schema is now per api), not give data (worst outcome), or give text and hope someone reads it. Operational support scenarios can be automated in the "let's get a human involved" pathway, and as long as we have no answer for this, no tool vendor will use this, making everything more complex, more isolated, and in turn, more expensive. If one of the variables is badly written and an invalid URI, and another one does not exist, and i've been teaching people to reuse errors they understand, i now have no standard way to explain that one problem is X and another is Y. Operational is part of APIs and automation is as important to DevRelOps as it is to just plain APIs.
Thank you NAME for the insights into how you're handling this issue. It's an interesting approach to the limitations of the original RFC and reflects what we're also trying to 'fix' with . Do you also return the attribute within the array to let the client know the severity of the problem? NAME it may be a waste of time at the moment, but when you know beforehand that fixing the space problem won't make the other problem(s) go away one could also think about correcting the before sending a new request. Yes, but isn't that a bad user experience? I'd rather know everything I'm doing wrong right now before making a new request, fixing one problem, making another request, fixing another problem, and so on.
It's certainly a trade off, but fixing one problem at a time is the best way to debug. Whenever I try to make more than one change at a time, I end up in a more chaotic debugging state than before. It's good practice to make isolated changes that you understand rather than throwing things at the wall to see what sticks. The trade off is that the media type is less flexible and certain things will be more difficult to convey. However, in my experience with the JSON:API spec (which supports multiple error objects), server implementers tend to dump useless stack traces into response bodies and try to abuse them to make non-atomic updates. Multiple errors also encourage client implementers to try the kitchen sink approach to debugging. So it's in the spirit of designing something that makes good practices easy and bad practices difficult that I'm pushing back against supporting multiple problem details. My suggestion is to finalize this document for the single error case. Then mint an error type called which defines an extension member named . The value of would be an array of problem objects as defined for the single error case. Perhaps it will add additional extension members for those child objects as well. To benefit from network effects, the type can be published using the IETF process. By separating that into its own document, you can iterate on that design in a separate document without postponing this one.
Yes we do, but this is only used for operators to gain additional insight. I'd be receptive to such a proposal
I'm with you on making bad practices difficult and good practices easy Sounds promising. I'd be willing to support this.

However, in my experience with the JSON:API spec (which supports multiple error objects), server implementers tend to dump useless stack traces into response bodies and try to abuse them to make non-atomic updates. I am not a proponent of JSON:API spec, but honestly, this has nothing to do with the multiple error objects. It is due to lack of knowledge/discipline/governance on the API developer's side. Someone can dump exception in even today. A few days ago, I had to explain to a very senior Java developer that you just cannot stream Java exceptions in error response of an HTTP API. >My suggestion is to finalize this document for the single error case. Then mint an error type called multiple which defines an extension member named instances. The value of instances would be an array of problem objects as defined for the single error case. Perhaps it will add additional extension members for those child objects as well. I disagree. Multiple problems could be added using extension mechanism today as well. One of the main reasons for -bis is to provide support for multiple problems without any extension (in order to increase adoption).
My .02 - If we define a type, some implementations are likely to use it by default, even when a single problem is transferred. That seems suboptimal, because it loses the mapping between the HTTP status code and the actual problem type. Also, a problem type would by necessity have to use a generic status code (probably ), thereby reducing semantics exposed in HTTP, which isn't something we should be recommending.
Looks like we are back to square one on the issue of support for multiple problems. Imho, having HTTP status code duplicated in the problem details response body was not desirable. Now, that it is in the RFC, its presence creates a real problem in supporting the multiple problems use case which is also a common use case in any HTTP API accepting requests with a slightly complex schema.
It's not a matter of whether or not the status code is duplicated; it's whether the semantics of the problem are appropriately reflected in the status code.
I think we're gravitating towards the (1) direction outlined above - 'Improve the documentation regarding how to handle multiple problems in extensions' We could do that by: Adding examples with multiple instances of the same problem in them Adding prose that explains how to handle different scenarios, such as: multiple instances of the same problem type multiple problems of different types
Discussed in 111: NAME to write preliminary PR.
Also, since we now have a registry, we could go ahead and define a problem type that handles multiple instances -- for example, 'json input validation error'. That might help tease out some of the issues here.
here is the model followed NAME URL we are using a fields causes that is defined as an array of object. use case is that for a given failure like a transaction several causes can be implied (ie first field not correct size, second not a number etc ) key design decision would be is this a single object so cause , or an array of object notice that the cause has been also introduce by Zalando URL that has been integrated with a Spring extension
Wouldn't multipart/related ] be a good fit for this?
Multi part tend to disapears in the API spaces as far as i can see (unfortunate or not) NAME , array is a better pattern for API , mutli part is usually attached to concept of differents payload encoding, that here i don't see the point for 99 % of use cases . if ever you requires a dedicated pdf file for the causes , it should go to a functional pattern or a custom extension of it following a keep it simple approach
This comment, as most of my comments on issues in repositories, got a bit out of hand and way too long. I'm sorry for that and my limited english vocabulary to make this a bit more compact. Although this issue seems to go into the opposite direction, I agree with URL by NAME but don't think there should even be a "multiple problems" option. Isn't there always a "root problem"? Or at least a "first problem" or "most important problem"? I don't feel like telling a client about only one problem at a time is bad user experience. It might seem like a bad user experience from the perspective of a human debugging their request by hand, but even then I personally think it's more logical to solve issues iteratively. Yes, one needs to eventually make multiple requests to fix their request, but considering today's average internet speed and the expected small size of problem details responses, I think it's just fine. But if we think about a computer program handling a problem details response and trying to "fix it", I think it becomes even more clear that only one problem at a time should be in a response. I realize this might be "opinionated", but a client app with multiple atomic handlers each able to "fix" one type of problem seems more sustainable and logical to me than either one huge handler that "fixes" all types of problems or a lot of handlers each fixing every possible combination of problems. I think this RFC and APIs should be designed considering that and at the moment it already feels optimal as is in this regard. If an API for some reason still has to respond with "multiple problems", it already can, just as described at the end of section 3: NAME in the first post of this issue states that the current version of the RFC "does not natively allow multiple problems to be conveyed", but I feel like it actually does. Even the example given after that quote from the RFC "conveys", at least to a human reader, that there are multiple problems, since the value of the field is "Your request parameters (plural) didn't validate." But actually, and I am trying to avoid going full philosophical here, isn't it true that every collection of problems can be seen as one big problem? And every single one problem could theoretically be split up into multiple problems. Let's take a look at the field of the first example: "Your current balance is 30, but that costs 50." Sure, the problem in this case is called "out-of-credit" and the obvious solution proposed is topping up the account with more credits. But this RFC didn't tell us this "obvious" solution, we came up with it and that's how it should be. The problem of not having enough credits on your account could theoretically be split up in the problem of you being a bit forgetful or the problem that the service is expensive or their pricing system isn't transparent enough. I realize this isn't the best example for what I'm trying to say, but I still hope you understand it. It is and only can be the responsibility of whoever implements the API and whoever implements the client, to write code that knows what problems to expect, how the field or an extension field is structured, which of them can be fixed and to then provide solutions for them. So I feel it is also their responsibility to write code that "knows" when to expect multiple problems, or a single one, or both. Even just the presence of an extension field called or can indicate that there are multiple problems that each have to be fixed separately. I think specifically defining some sort of "multiple" type or field is not the optimal strategy here and goes against the spirit of freedom across the rest of this RFC. I realize the purpose of a standard is not to embrace freedom and doing things completely different to anyone else . But defining a specific structure for conveying that there are multiple problems could be dangerous and actually impede adoption, in my opinion. For example, if my API only detected a single validation error, does my server now need to flip the boolean value? Is now still an array with just one object in it, or just one object, so actually a different data structure my client needs to handle specifically? If it's always an array why even use the field? My client will iterate over the array anyway and doesn't care how big it is. I think keeping this aspect of the RFC as is would be a great opportunity to let the community dynamically decide on a best practice and eventually draft a separate document once there is more consensus and more people worked with this specification in the real world. I definitely don't think the current specification doesn't hinder anyone from handling multiple problems. In the case of form validation for example, where you might only want to send one request for the whole validation, sure, feel free to let the API respond with an array of validation errors in a custom extension field. A client submitting a form will already expect a specific structure of response anyway. As I said, abstractly seen, a multitude of validation errors is still only one specific "big" problem, namely that there are validation errors. The details of those problems can then be described in either the field and/or a custom extension field.
going back to NAME initial comment, i am in favor of option 0, which is to do nothing. if we go down the path of showing speculative extensions, we kind of "define" them without really defining them. that in my mind is the real risk of showing hypothetical extensions in examples. people will use them, regardless how clearly you say "this is not actually an extension and just for illustration".
So, with NAME PR merged a while back, we currently: Describe how to design extensions to accommodate multiple instances of the same type Describe how to use to convey multiple problems with different types/status codes Do not describe how one might convey multiple problems with different types but the same status code. I think (1) is fine and good. Right now, (2) seems like it's recommending the pattern, but doesn't define an actual type for use in that situation. That's not great. If we're going to show that pattern, we should probably define the type for use in that situation (especially since we have a registry now). However, I have serious doubts about the wisdom of recommending that pattern, and feel like we should either remove that text, or at least heavily contextualise it. Regarding (3) -- again, if we want to document that, we should define a type. I tend to think we shouldn't, though. If we retract (2) and don't attempt (3), we might want to add some text along the lines of:
i agree. showing something without defining it in the end will be a "bad definition" because people will take it as shown and run with it. my vote goes to removing it. same here. i like it.
If we retract (2) and don't attempt (3), we might want to add some text along the lines of: >"When an API encounters multiple problems that do not share the same type, it is RECOMMENDED that the most relevant or urgent problem be represented in the response. While it is possible to create generic "batch" problem types that convey multiple, disparate types, they do not map well into HTTP semantics." +1
OK. It seems like we agree here -- I'll ping the mailing list and make sure everyone is aware / on board.
my 2 cents , when you do a REST request you expect to have a single status , this is the HTTP status , here a 4XX or 5XX, for sure not a 207 that is part of 2XX section so a success HTTP requires it fails or it succeed what problem RFC provides is a more standard way to return feedback about this status ... this is where 'problem' is used RFC problem describes the http status of error with standardized information (title , details, type) This status can have multiple root cause this is why having as an array is a good pattern . it is not an array of problem (it wont make sense according to the definition of http problems) but an array of cause. you can have a single explanation of a return that can be explained due to various cause cause could be ... either free form (easiest) , here is a use case about Form filling that is failing . Cause can be the list of fieldName and Value in default but this does not fit all use cases { "type": "URL", "title": "The request is invalid", "status": 400, "detail": "Customer Creation Failure", "causes": [ { "title": "The name is too Long", "field": "name", "fieldValue": "AsuperExtraLongName" }, { "title": "Date of Birth is in the future", "field": "dateOfBirth", "fieldValue": "20/20/2200" } ] } another pattern can be to have recursive causes definition ... but this is too munch prescriptive { "type": "URL", "title": "The request is invalid", "status": 400, "detail": "Cannot create Order", "causes": [ { "type": "URL", "title": "Order Management ; one of the item cannot be fulfilled ", "status": 404, "detail": "Item management , item XXX cannot be found ", causes [ type": "URL", "title": "Storage", "status": 400, "detail": "Item XXX is out of stock", } }] }

"problem-pointer" to locate the problem within the request's content using a JSON Pointer RFC6901.  <ins> When an API encounters multiple problems that do not share the same type, it is RECOMMENDED that the most relevant or urgent problem be represented in the response.  While it is possible to create generic "batch" problem types that convey multiple, disparate types, they do not map well into HTTP semantics. </ins> 3.1.


This specification defines the HTTP Problem Type registry for common, widely-used problem type URIs, to promote reuse. <del> A Designated Expert reviews and approves registration requests, as per RFC8126, Section 4.5.  A specification document is appreciated, but not required. </del>  When evaluating requests, the Expert(s) should consider community feedback, how well-defined the problem type is, and this specification's requirements.  Vendor-specific, application-specific, <del> and deployment-specific values are not registrable. </del>  Registrations MAY use the prefix "https://iana.org/assignments/http- <del> problem-types#", and are encouraged to do so when a stable, neutral URI is desirable. </del>  Registration requests should use the following template:

Currently: That doesn't seem like a recipe for good interop. While it doesn't need to be an RFC, some sort of reference is necessary...
I'm sorry, but I don't quite understand what is being referred to here. Is the quoted paragraph from RFC7807? Because I can't find it. Without more context I also don't quote understand what it is referring to.
NAME https://ietf-wg-URL

This specification defines the HTTP Problem Type registry for common, widely-used problem type URIs, to promote reuse.  <ins> The policy for this registry is Specification Required, per RFC8126, Section 4.5. </ins> When evaluating requests, the Expert(s) should consider community feedback, how well-defined the problem type is, and this specification's requirements.  Vendor-specific, application-specific,  <ins> and deployment-specific values are not registrable.  Specification documents should be published in a stable, freely available manner (ideally located with a URL), but need not be standards. </ins> Registrations MAY use the prefix "https://iana.org/assignments/http-  <ins> problem-types#" for the type URI. </ins> Registration requests should use the following template:


Abstract This document defines a "problem detail" to carry machine-readable <del> details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs. </del>  1. consumers of HTTP APIs have difficulty doing so. To address that shortcoming, this specification defines simple JSON <del> RFC8259 and XML XML document formats to describe the specifics of problem(s) encountered - "problem details". </del>  For example, consider a response indicating that the client's account doesn't have enough credit.  The API's designer might decide to use 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.  3. The canonical model for problem details is a JSON RFC8259 object. starting with "*".  To avoid conflicts, extension member names SHOULD NOT start with the "*" character.  4.  When an HTTP API needs to define a response that indicates an error condition, it might be appropriate to do so by defining a new problem type. it can be serialized in formats other than JSON), and they SHOULD be three characters or longer. <del> 4.1. </del>  For example, if you are publishing an HTTP API to your online shopping cart, you might need to indicate that the user is out of appropriate title and the HTTP status code that it will be used with, along with what it means and how it should be handled. <del> 4.2. </del>  This specification defines the HTTP Problem Type registry for common, widely-used problem type URIs, to promote reuse. See the registry at https://iana.org/assignments/http-problem-types [1] for details on where to send registration requests. <del> 4.2.1. </del>  This specification registers one Problem Type, "about:blank". member.  Consequently, any problem details object not carrying an explicit "type" member implicitly uses this URI. <del> 5. </del>  When defining a new problem type, the information included must be carefully vetted.  Likewise, when actually generating a problem - and virus scanners) are unlikely to know of or respect the status code conveyed in this member. <del> 6. </del>  Please update the "application/problem+json" and "application/ <del> problem+xml" registrations in the Internet media types registry RFC6838. to refer to this document. </del>  <del> Please create the HTTP Problem Types Registry, as specified in </del>  registry, and populate it with "about:blank" as per blank. <del> 7.  References </del>  <del> 7.1.  URIs </del>  [1] https://iana.org/assignments/http-problem-types

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 cannot 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 doesn'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: Find a naming convention that doesn't conflict with existing usage (e.g., a prefix) Mint a new media type (1) is hard, because we don't and can'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 isn't too upsetting for JSON 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, JSON Schema). 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 aren'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 added 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 doesn'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 don'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: URL
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", NAME URL 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 (URL) 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 NAME
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 NAME
Thank you for the ping NAME I agree with NAME 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 NAME was writing about. TBH, it still feels weird to have problem details in the body and warnings in the header. Shouldn'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 NAME 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. Problem Details in the body. Warning Details 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 don't seem feasible, due to the side effects stated above. NAME 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 wouldn't seem right to have problem details being returned as the only content.
liking NAME reasoning here which could mean for RFC7807bis to potentially subsume the URL 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 NAME 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 don'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? Shouldn't the fields be delimited with a semicolon ?
NAME 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 metadata as that of RFC 7807. And as NAME 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 don'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.
NAME the problem object can only serialise one problem, I think the same would apply here.
Hey NAME 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 won'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 don't really see the point in having problems/warnings in a header field. Isn'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 don'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/myapp+json" 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 can't afterwards access the HTTP-Headers of this page in Javascript (I had too look that up here: URL) . 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...
NAME 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 can't see too many risks of including it in the spec (obvious worst case: it doesn't get used). That's not enough to justify including it, of course. NAME NAME 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 cannot 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.

Abstract This document defines a "problem detail" to carry machine-readable  <ins> details of errors in HTTP response content and/or fields to avoid the need to define new error response formats for HTTP APIs. </ins> 1. consumers of HTTP APIs have difficulty doing so. To address that shortcoming, this specification defines simple JSON  <ins> RFC8259 and XML XML document formats and a HTTP field to describe the specifics of problem(s) encountered - "problem details". </ins> For example, consider a response indicating that the client's account doesn't have enough credit.  The API's designer might decide to use 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here. <ins> This document uses the following terminology from STRUCTURED-FIELDS to specify syntax and parsing: Dictionary, String, and Integer. </ins> 3. The canonical model for problem details is a JSON RFC8259 object. starting with "*".  To avoid conflicts, extension member names SHOULD NOT start with the "*" character. <ins> 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. </ins> 4. <ins> 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 Problem HTTP field allows a limited expression of a problem object in HTTP headers or trailers.  It is a Dictionary Structured Field (Section 3.2 of STRUCTURED-FIELDS) that can contain the following keys, whose semantics and related requirements are inherited from problem objects: the type value (see type), as a String the status value (see status), as an Integer The title value (see title), as a String The detail value (see detail), as a String The instance value (see instance), as a String 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. For example: 5. </ins> When an HTTP API needs to define a response that indicates an error condition, it might be appropriate to do so by defining a new problem type. it can be serialized in formats other than JSON), and they SHOULD be three characters or longer.  <ins> 5.1. </ins> For example, if you are publishing an HTTP API to your online shopping cart, you might need to indicate that the user is out of appropriate title and the HTTP status code that it will be used with, along with what it means and how it should be handled.  <ins> 5.2. </ins> This specification defines the HTTP Problem Type registry for common, widely-used problem type URIs, to promote reuse. See the registry at https://iana.org/assignments/http-problem-types [1] for details on where to send registration requests.  <ins> 5.2.1. </ins> This specification registers one Problem Type, "about:blank". member.  Consequently, any problem details object not carrying an explicit "type" member implicitly uses this URI.  <ins> 6. </ins> When defining a new problem type, the information included must be carefully vetted.  Likewise, when actually generating a problem - and virus scanners) are unlikely to know of or respect the status code conveyed in this member.  <ins> 7. </ins> Please update the "application/problem+json" and "application/  <ins> problem+xml" registrations in the "Media Types" registry to refer to this document. </ins>  <ins> Please create the "HTTP Problem Types Registry" as specified in </ins> registry, and populate it with "about:blank" as per blank.  <ins> Please register the following entry into the "Hypertext Transfer Protocol (HTTP) Field Name Registry": Problem Permanent RFC nnnn 8.  References </ins>  <ins> 8.1.  URIs </ins> [1] https://iana.org/assignments/http-problem-types


that they don't recognize; this allows problem types to evolve and include additional information in the future. <del> Note that because extensions are effectively put into a namespace by the problem type, it is not possible to define new "standard" members without defining a new media type. </del>  4.

Following the discussion in made me think that we could tighten the language around extension member scope. "Effectively" seems a bit odd here. Are they put into a namespace or not? If they do, then processing rules follow that we may want to spell out: Maybe that's not good wording, but it seems to me that the current wording may be a little too vague.
I just realized that my above text clashes with URL but once that one is merged I can come up with a suggestion that works with the updated draft text.
I don't think adding new requirements here is a good idea. I've tweaked a bit to make things clearer.
this proposal wasn't meant as adding new requirements, but as clarifying rules that may have been implicit before. thanks for the tweaks.
(, 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 cannot 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 doesn'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: Find a naming convention that doesn't conflict with existing usage (e.g., a prefix) Mint a new media type (1) is hard, because we don't and can'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 isn't too upsetting for JSON 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, JSON Schema). 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 aren'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 added 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 doesn'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 don't do the header field now, doing something compatible with SH dictionaries seems like a good idea so that it's future-proof.

that they don't recognize; this allows problem types to evolve and include additional information in the future.  <ins> Future updates to this specification might define additional members that are available to all problem types.  To avoid conflicts, extension member names SHOULD NOT start with the "*" character. </ins> 4.


The "type" member is a JSON string containing a URI reference URI that identifies the problem type.  Consumers MUST use the "type" URI <del> (after resolution, if necessary) as the problem's primary identifier. </del>  When this member is not present, its value is assumed to be "about:blank".

It seems that saying could be read as identifying the problem instance rather than identifying the problem type. Here's a minor edit to make this more explicit: It's not quite clear to me what other identifiers could be (patterns of extension members, maybe?), but that's a different question.

The "type" member is a JSON string containing a URI reference URI that identifies the problem type.  Consumers MUST use the "type" URI  <ins> (after resolution, if necessary) as the problem type's primary identifier. </ins> When this member is not present, its value is assumed to be "about:blank".


Despite the following behavior being misguided, experience has shown that some customers use the IANA registry as a checklist against which to measure an implementation's completeness, and some <del> implementers blindly implement supported group.  Therefore, IANA [SHALL add/has added] the following warning to the registry: </del>  IANA [SHALL update/has updated] the reference for this registry to <del> also refer to this document. </del>  The value 0 (0x0000) has been marked as reserved.

Tweaks for Supported Groups. We still need to figure out what to do with curves smaller than 256.

Despite the following behavior being misguided, experience has shown that some customers use the IANA registry as a checklist against which to measure an implementation's completeness, and some  <ins> implementers blindly implement supported group.  Therefore, IANA has added the following warning to the registry: </ins> IANA [SHALL update/has updated] the reference for this registry to  <ins> refer to this document instead of RFC8447. </ins> The value 0 (0x0000) has been marked as reserved.


has renamed entry 35 to "session_ticket (renamed from "SessionTicket TLS")" RFC5077. <del> [SHALL replace/has replaced] the reference to RFC8447 with a reference to this document in the "Reference" column for entry 35. </del>  7. <del> Experience has shown that the IETF Review registry policy for TLS extensions was too strict.  Based on WG consensus, the decision was taken to change the registration policy to Specification Required while reserving a small part of the code space for Private Use RFC8126.  Therefore, IANA [SHALL update/has updated] the TLS ExtensionType Values registry as follows: </del>  <del> Changed the registry policy to: </del>  <del> Updated the "Reference" to refer to this document instead of RFC8447. </del>  <del> See expert-pool for additional information about the designated expert pool. Despite wanting to "loosen" the registration policies for TLS extensions, it is still useful to indicate in the IANA registry which extensions the WG recommends be supported.  Therefore, IANA [SHALL update/has updated] the TLS ExtensionType Values registry as follows: Add a "Recommended" column with the contents as listed below. This table has been generated by marking Standards Track RFCs as "Y", "truncated_hmac" (4) and "connection_id (deprecated)" (53) as "D", and all others as "N".  The "Recommended" column is assigned a value of "N" unless explicitly requested, and adding a value with a "Recommended" value of "Y" requires Standards Action RFC8126.  IESG Approval is REQUIRED for a Y->N, Y->D, and D->Y|N transitions. </del>  <del> IANA [SHALL update/has added] the following notes: The extensions added by I-D.ietf-tls-rfc8446bis are omitted from the above table.  Likewise, extensions defined after RFC8447 are also not listed in the table as those RFCs specify the value of the extension's "Recommended"; extensions points defined after RFC8447 include token_binding, compress_certificate, record_size_limit, pwd_protect, pwd_clear, password_salt, ticket_pinning, tls_cert_with_extern_psk, delegated_credentials, supported_ekt_ciphers, connection_id, external_id_hash, external_session_id, quic_transport_parameters, ticket_request, and dnssec_chain. I-D.ietf-tls-rfc8446bis also uses the TLS ExtensionType Values registry originally created in RFC4366.  The following text is from I-D.ietf-tls-rfc8446bis and is included here to ensure alignment between these specifications. IANA [SHALL update/has updated] this registry to include the "key_share", "pre_shared_key", "psk_key_exchange_modes", "early_data", "cookie", "supported_versions", "certificate_authorities", "oid_filters", "post_handshake_auth", and "signature_algorithms_cert", extensions with the values defined in I-D.ietf-tls-rfc8446bis and the "Recommended" value of "Y". IANA [SHALL update/has updated] this registry to include a "TLS 1.3" column that lists the messages in which the extension may appear.  This column [SHALL be/has been] initially populated from the table in Section 4.2 of I-D.ietf-tls-rfc8446bis with any extension not listed there marked as "-" to indicate that it is not used by TLS 1.3. </del>  8.

It might be clearer to have the document update RFC 8447 instead of obsolete. This would make the changes more targeted and may make the document easier to review and apply to the existing registry. It also contains text for issue
rewrote Extensions section as an update instead of obsolete. Included proposal for recommended note
Obsoleting RFC 8447 means duplicating a lot of text and making changes to it which makes the document have awkward wording and makes the changes difficult to follow. I think it would be clearer if it were an update and just listed the changes. see Extension Types PR
At IETF 115, there was general agreement that this document could be an update as opposed to an obsolete to make it easier on IANA.
Some registries have values that are reserved because the values were "burned". These values are not in private use space but are mid-range, 40 in the ExtensionType registry. Should we mark these as "D"?
I think we should make those as D. Addressed in PR
NAME agreed. Will close this out.
Currently the I-D includes the following note: Note: : If an item is not marked as "Recommended", it does not necessarily mean that it is flawed; rather, it indicates that the item either has not been through the IETF consensus process, has limited applicability, or is intended only for specific use cases. Now that we have three values do we need to expand this to also include "D".
Proposed text in PR

has renamed entry 35 to "session_ticket (renamed from "SessionTicket TLS")" RFC5077.  <ins> [SHALL replace] the references to RFC8447 with a reference to this document in the "Reference" column for entry 35. </ins> 7.  <ins> In order to refect the changes in the Recommended column allocation, IANA SHALL update the TLS ExtensionType Values registry as follows: </ins>  <ins> Change the registry policy to: </ins>  <ins> Add a reference to this document under the reference heading. </ins>  <ins> Update the "Recommended" column with the changes as listed below. This table has been generated by keeping existing "Y" and "N" entries except for "truncated_hmac" (4), "connection_id (deprecated)" (53), "reserved" (40) and "Reserved" (46) as "D".  A reference to this document SHALL be added to these entries. </ins>  <ins> Update the following note on the recommended column </ins> 8.