Media Type Directives and Mapping

Unsupported schema directives invalidate the API spec registration.

Schema directives incompatible with a request body or response entity schema cause errors during callout.

You can register specifications with nonsupported or incompatible consumes, produces, or OpenAPI 3.0 content media type directives by mapping the media types to supported media types. For more information about media type mapping, see What is Media Type Mapping?.

Missing schema directives are defaulted to:

• application/json—if the request body or the response body schema is either an object or an array
• text/plain—if the request or response schema body is a primitive type such as a string or an integer number

If no request body parameter is defined for methods POST, PUT, and PATCH, form data request parameters are sent in the request body as application/x-www-form-urlencoded.

The applicable media type in the OpenAPI 2.0 produces list, OpenAPI 3.0 response schema media types, or a default (application/json, or text/plain), is set as the HTTP Accept header.

What is Media Type Mapping?

You can map each nonsupported, custom media type instance (defined in your API spec) to a supported media type of the same format. Supported media types for both requests and responses are:

• application/json—Structured data in JSON format.
• text/plain—Unstructured data as plain text.
• application/x-www-form-urlencoded—URL encoded form.

For example, if your spec includes a customized media type application/abc.api+json and the formatting adheres to standard JSON formatting, then map this custom media type to application/json.

You can perform this mapping by either Mapping Media Types During Registration (the declarative, easy way) or by Mapping Media Types with Metadata API (which involves manual coding).

Custom media types with a supported media type suffix are recognized as one of the compatible supported media types. For example, a custom or vendor media type application/vnd.api+json with media type suffix json is recognized as application/json.

Supported media type suffixes:

• json—Structured data in JSON format.

For information about OpenApi 2.0 consumes/produces or OpenAPI 3.0 content media type schema directives, see Schema Definition Support.