Adding support for error or warning meta information to OpenAPI 3 Specifications

[sekharbans]

Note: This issue has been discussed before - but will make an attempt to re-propose supporting error and warning meta information.

The Proposal - Summary

Adding the support for error or warning meta information for operations to the OpenAPI 3.0 specifications.

The current workaround used by many organizations is to use extensions and define their own error containers.

Given the commonality in error handling patterns across the industry - it is suggested that a specification as rich as OpenAPI 3.0 should formalize and standardize on this as an optional supported feature.

Additional justifications for the elements suggested are further discussed at the end of this document after laying out the proposed changes.

Proposed Specification Changes:

Add an optional ‘errorContent’ fixed field to the Response object that would have the following definition:

Field Name	Type	Description
description	string	REQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
headers	Map[string, Header Object | Reference Object]	Maps a header name to its definition. RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content	Map[string, Media Type Object]	A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links	Map[string, Link Object | Reference Object]	A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects.
errorContent	Map[string,[Error Object]]	A list of errors that might be emitted as a response. The string is intended as a logical grouping of the errors (for example a severity aspect that could have values ‘errors’ or ‘warnings’ ).It is proposed that we leave the logical groupings to the users defining the contracts. We impose no constraints.

Error Object
Describes a single error response that could result from an API Operation

Fixed Fields

Field Name	Type	Description
code	string	REQUIRED. A canonical representation of the error (alternate name - errorId?).
domain	string	Returns the domain to which the code belongs
description	string	A short description of the specific code. CommonMark syntax MAY be used for rich text representation.

A Responses Object Example with the proposed changes:

Success Response with Warnings example:

{
	"200": {
	"description": "a pet to be returned",
		"content": {
			"application/json": {
				"schema": {
					"$ref": "#/components/schemas/Pet"
				}
			}
		},
		"errorContent": {
			"warnings": [{
					"code": "101",
                                         "domain": "diet",
					"description": "Pet may be hungry"
					
				},
				{
				"code": "102",
                                "domain": "security",
			       "description": "Pet may be unleashed"
					
				}
			]
		}
	},

Response with Errors example:

	"409": {
		"description": "Conflict",
		"errorContent": {
			"errors": [{
				"code": "REASSIGNED",
				"domain": "admin",
				"description": "Pet has been assigned to a different owner"
			
			}]
		},
		"content": {
			"application/json": {
				"schema": {
					"$ref": "#/components/schemas/ErrorModel"
				}
			}
		}

	},
	"default": {
		"description": "Unexpected error",
		"content": {
			"application/json": {
				"schema": {
					"$ref": "#/components/schemas/ErrorModel"
				}
			}
		}
	}
}

Justifications:

The case for ‘error code’:

There is a line of thought that prescribes the use of http status codes exclusively or perhaps in tandem with a descriptive error message - but that may not work too well for complex use cases.

An example would be an operation which might throw multiple say business errors against a http status 409 (Conflict) each of which, based on the discretion of the client may be either:

• Canonicalized to a more generic error ( for example: granular errors returned by payment gateways are often canonicalized to simpler errors that are surfaced on client apps)
• Be differently handled ( for example a certain error scenario may result in a redirect - for example “xxx is no longer available - here are a few similar ones” OR a message to be shown to the user “The price and terms and conditions have changed - would you like to proceed?”)
• Simply messaged ( here also there are client side use cases that often use custom messaging )

For each of the examples above the preference is to use a more canonical form of an error descriptor identifier rather than an error message.

The case for Domain:

There are use cases where the domain needs to be associated with the error being returned to prevent conflicts and guarantee uniqueness

Wrap up

Given the widespread usage of error codes in API integrations - it would be really nice to have a consistent but an optional way to handle the metadata around errors and warnings - at least from an exploratory point of view.

[JordiPolo]

Why not just add schemas to "4xx", "5xx" responses?

[sekharbans]

Its not so much about the structure of an error response or the default. OpenAPI 3 already provides for that - but supplying vital error / warnings meta information ( of interest from an integration standpoint ). Please refer to the 'justifications' section that explains the intent with a few examples. However i concede 'errorContent' is misleading and should be perhaps better named. Does 'additionalInfo' do justice?

[handrews]

This is much better handled through media types such a application/problem+json.

In particular, sub-codes are a controversial topic. I avoid them like the plague, given the option, and instead take advantage of the extensibility of problem+json to return whatever structured error data is most useful for automated handling. For human handling, a cryptic numeric code is useless. Just use an error string that is recognizable in bug reports.

My point with the above paragraph is not to convince anyone to avoid sub-codes. They are quite popular and should be available for APIs that want to use them. Rather my point is that I don't think it is a benefit if OpenAPI were to be more restrictive. OpenAPI's flexibility is, in my opinion, a major asset.

If you want to see a standardized error structure, I would instead propose another error media type if problem+json doesn't work for you.

[JordiPolo]

@handrews I do not particularly like subcodes either but have not found a better solution to decoupling UI errors from the server.

Specially for validation errors, we send back things like "missing_key" as code, then the UI can be deployed with a mapping of this to errors in every language we support.
I really do not want to add that info to the server.

our mimetype is application/json but we still add a schema to represent 422 and other codes in our openapi file.

Thoughts?

[handrews]

@JordiPolo I guess I don't understand the relationship between the data structure you want to add to the OpenAPI file and the structure of the error response.

I also just don't see any meta-data that is both sufficiently universal to warrant standardizing via OpenAPI, and that is not already handled through other existing standards like problem+json

[JordiPolo]

@handrews I agree, I'm saying this issue can be solved by just adding a schema to the error response and there each user specifies whatever.

I've just read the RFC for application/problem+json, it's not bad but I wish it had more examples.

[handrews]

@JordiPolo I just don't understand what errorContent is for, then. Can't you already give a schema with content? Why would there be a need for errorContent on a 200 response?

[sekharbans]

@handrews - a 200 could have warnings. The intent behind this proposal is to surface error/warning information in a clean standardized way (arguably this could also be part of the description ) - but the Specification already provides an excellent structure at an Operation / Response level - it is just supplementing that with some additional standardized response meta information that is of great interest to anyone integrating with that API. (Error codes continue to be widely used - and I have tried to layout a few use cases in the justifications section why they are).

[sekharbans]

Here are a few Industry examples - if that helps decide a standardized support format. As I have noted before 'errorContent' is perhaps misleading from the intent and needs to be modified. It is additional response meta information ... The use case could be better described as: "As a developer integrating with a complex API I need information on the different error or warnings relevant to an endpoint"

Stripe
https://stripe.com/docs/api/curl#errors
eBay
https://developer.ebay.com/api-docs/buy/order/resources/guest_checkout_session/methods/getGuestCheckoutSession
CyberSource
http://apps.cybersource.com/library/documentation/dev_guides/Tax_SO_API/html/wwhelp/wwhimpl/js/html/wwhelp.htm#href=appReasonCodesSO.html

[handrews]

I still see no reason to standardize anything other than using a standardized response media type. But I'm probably not really your target audience here (and I have nothing to do with decision-making for OAI so you needn't worry there :-)

As for warnings, I try to avoid them. Something is either worth taking action on or it is not. In my experience, warnings are ignored to the point of being useless. But if I were to do anything with them, I would look at the HTTP Warning header

[sekharbans]

If we were to have this support - (totally leave that to you folks) - but in case we do, based on this discussion I am somewhat inclined towards a more generic 'responseCode' than error codes or warnings as in my original proposal. The altered 'errorContent' could instead be:

'additionalInfo' - Map[string,[ResponseCode Object]] - A list of response codes relevant to the operation. The string is intended as a logical grouping of the response codes (for example a severity aspect that could have values ‘errors’ or ‘warnings’ ).It is proposed that we leave the logical groupings to the users defining the contracts. We impose no constraints.

Is that something that would have some agreement :) ?

An altered example would be ...

	"200": {
	"description": "a pet to be returned",
		"content": {
			"application/json": {
				"schema": {
					"$ref": "#/components/schemas/Pet"
				}
			}
		},
		"additionalInfo": {
			"warnings": [{
					"code": "101",
                                         "domain": "diet",
					"description": "Pet may be hungry"
					
				}
			]
		}
	},```

[darrelmiller]

When I want to introduce warnings into a response, I borrow the warning header from the HTTP caching spec. It was designed to be generalized https://tools.ietf.org/html/rfc7234#section-5.5

From my perspective, OpenAPI is intended to describe HTTP APIs using HTTP semantics. I don't want us to be in the business of inventing our own application semantics. Having a property called "additionalInfo" is waving a red flag saying "put your out of band coupling here".

[sekharbans]

We could revisit the names (the 'warning' above was just an example).

It would be totally awesome if we could factor in some standardized way to declare response codes (which are essentially more specific 'subcodes' to the primary HTTP status codes )and do have widespread usage. Of course in a manner that does'nt in anyway contradict OpenAPI principles.

But if the consensus is to deny - we could close this topic.

[darrelmiller]

@sekharbans I feel that you are pitching your ideas to the wrong working group. If you believe that HTTP status codes are insufficient to describe the semantics of the response to a HTTP request then you should be talking to the HTTP working group. We are just in the business of being able to describe HTTP APIs, nothing more.

[handrews]

@sekharbans while as noted before I have no particular standing with this project, I agree with @darrelmiller here. I've been re-surveying the available API technologies recently and I feel that OpenAPI's strength is its flexibility to work with whatever HTTP-based APIs are out there rather than imposing its own views. Standardizing content (error content or otherwise) would go against that.

[darrelmiller]

Reviewed by TSC (meeting 2017-12-15). Recognized that this is a valid requirement, but not convinced this is the right approach. More review required.

[MikeRalphson]

See also #567

Much as links in OAS 3.0 don't serve to replace or mandate existing HTTP/hypermedia standards, but merely document how information can be used from responses, I'm tempted to suggest (for existing/legacy APIs which do not follow RFC7807 Problem Details for HTTP APIs) a method to document where analogous properties to those in RFC7807 are to be found.

For example:

responses:
  '200':
    description: OK
    ...
      warnings:
        title: $response.body#/warning/code
        detail: $response.body#/warning/description
  '403':
    description: Forbidden
    ...
      errors:
        title: $response.body#/error/code
        detail: $response.body#/error/description
        instance: $response.body#/error/moreInformation

For documentation purposes a values map for titles (error/warning codes) could be included.

The expression syntax (borrowed from links and callbacks) could also be expanded if necessary (i.e. to allow multiple errors/warnings per response).

[sekharbans]

A very happy new year folks and thanks so much for considering the request.

Wanted to point out that the response structure for errors can be defined in the contract
(refer to the 403s in this example).

What remains is therefore a standardized way to surface the different Id definitions. So simply a standardized way of documenting a values map as proposed by @MikeRalphson would probably suffice.

[handrews]

I'm pretty sure that as of OAS 3.1, anyone who wants to standardize on an error/warning envelope for their API can define a re-usable template structure using dynamic references. Is there something else here that needs doing?

[LasneF]

Closing this ticket as it pertains to error modeling. The OAS does not evaluate the quality of data or error models but provides tools for designers to create their models.

This concern could be addressed in an ‘API guidelines’ topic, which is not included here, as it is usually highly opinionated and debatable.

with the current state of the OAS there should not be no gap to build your own model