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

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.

[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”.

[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.