OpenAPI Compatibility Chart

This OpenAPI Compatibility Chart aims to document every part of the OpenAPI Specification that we do and don't support, as well as any quirks that might be present that you should be aware of.

We currently support OpenAPI through v3.1.0. For Swagger 2.0 support we use a tool called swagger2openapi that upconverts Swagger definitions to OpenAPI 3.0.

📘

Unless mentioned otherwise, all description properties that we support are run through our Markdown engine: RDMD

OpenAPI Object

📚 Specification Link

• openapi
  • We currently support everything up through 3.1.0.
• info – Info Object
• jsonSchemaDialect
  • jsonSchemaDialect is new to OpenAPI 3.1. See JSON Schema Dialects for a list of dialects that we support. ✅
• servers – Server Object
• paths – Paths Object
• webhooks - Map containing Path Item Object and/or Reference Object
  • OpenAPI definitions can contain a mix of paths and webhooks — as of January 2024, we support both. ✅
• components – Components Object
• security – Security Requirement Object
  • We support both global and operation-specific security requirements. ✅
• tags – Tag Object
• externalDocs – External Documentation Object

Info Object

📚 Specification Link

• title ✅
• summary ✅
  • summary is new to OpenAPI 3.1.
  • This value is surfaced in the API Info table on the Getting Started page.
• description ✅
  • This value is surfaced in the API Info table on the Getting Started page.
• termsOfService ✅
  • This value is surfaced in the API Info table on the Getting Started page.
• contact ✅
  • See Contact Object for more details.
  • This object is surfaced in the API Info table on the Getting Started page.
• license ✅
  • See License Object for more details.
  • This object is surfaced in the API Info table on the Getting Started page.
• version ✅
  • For certain OpenAPI definition upload methods, we use this value to determine what version of your docs to place your API definition. See Versions for more information on docs versions. Below, we go over the different upload methods:
    • When uploading via rdme, this value is ignored by default. To use this value, you can pass the useSpecVersion flag.
    • When uploading via the API, this value is used only if the x-readme-version request header is omitted.
    • This value is ignored by default in file uploads.

Contact Object

📚 Specification Link

👍

This object is surfaced in the API Info table on the Getting Started page.

• name ✅
• url ✅
• email ✅

License Object

📚 Specification Link

👍

This object is surfaced in the API Info table on the Getting Started page.

• name ✅
• identifier ✅
  • identifier is new to OpenAPI 3.1.
• url ✅

Server Object

📚 Specification Link

• url ✅
• description ✅
• variables ✅
  • See Server Variable Object for more details.

Server Variable Object

📚 Specification Link

• enum ✅
• default ✅
• description ✅

Components Object

📚 Specification Link

👍

With the exception of securitySchemes, all components that can be loaded as a $ref pointer are dereferenced prior to rendering.

• schemas – Schema Object
• responses – Response Object
• parameters – Parameter Object
• examples – Example Object
• requestBodies – Request Body Object
• headers – Header Object
• securitySchemes – Security Scheme Object
• links – Link Object
• callbacks – Callback Object
• pathItems – Path Item Object
  • pathItems is new with OpenAPI 3.1.

Paths Object

📚 Specification Link

👍

We support the Path Object because we wouldn't offer an API Reference without them. 😀

Path Item Object

📚 Specification Link

• $ref ✅
  • All $ref pointers are dereferenced prior to rendering.
• summary ✅
• description ✅
• get ✅
• put ✅
• post ✅
• delete ✅
• options ✅
• head ✅
• patch ✅
• trace ✅
• servers ⛔
  • We currently do not support servers declarations at the Path Item level. See Server Object for more details.
• parameters ✅

Operation Object

📚 Specification Link

• tags ✅
• summary ✅
• description ✅
• externalDocs ⛔
  • See External Documentation Object for more details.
• operationId ✅
• parameters ✅
  • See Parameter Object for more details.
• requestBody ✅
  • See Request Body Object for more details.
• responses ✅
  • See Responses Object for more details.
• callbacks ✅
  • See Callback Object for more details.
• deprecated ✅
• security ✅
  • See Security Requirement Object for more details.
• servers ⛔
  • We currently do not support servers declarations at the Operation level. See Server Object for more details.

External Documentation Object

📚 Specification Link

🚧

We currently only surface the External Documentation Object within the Tag Object of your documentation.

• description ✅
• url ✅

Parameter Object

📚 Specification Link

• name ✅
• in ✅
• description ✅
• required ✅
• deprecated ✅
• allowEmptyValue ✅
  • To add an empty value into our API Explorer you must first type in something and then delete it.
• style ✅
• explode ✅
• allowReserved ✅
• schema ✅
  • See Schema Object for more details.
• example ✅
• examples ✅
• content ⛔

Style Values

📚 Specification Link

Support for parameter style serialization:

🚧

spaceDelimited and pipeDelimited support on query and form-data parameters, while new to OpenAPI 3.1, is currently untested on our platform.

Request Body Object

📚 Specification Link

• description ✅
• content ⚠️
  • Though we support content, the API Reference only supports one Media Type at a time; so if you have a content declaration that has two Media Types we'll use either the first out of the list or whichever is JSON-compatible.
• required ✅

Media Type Object

📚 Specification Link

• schema ✅
• example ✅
• examples ✅
• encoding ⚠️
  • We only support encoding for multipart/form-data media types.

Encoding Object

📚 Specification Link

🚧

We only support the Encoding Object on multipart/form-data media types.

• contentType ⛔
• headers ⛔
• style ⚠️
  • We support the style parameter for multipart/form-data media types. See the style support list for more details.
• explode ⚠️
  • We support the explode parameter for multipart/form-data media types. See the style support list for more details.
• allowReserved ⛔

Responses Object

📚 Specification Link

For Responses we support default, blanket 1XX, 2XX, 3XX, 4XX, and 5XX statuses, as well as all HTTP status codes that are listed within with IANA Status Code Registry.

🚧

Any HTTP status code that is used but not listed below will be shown but internally treated as a general <number>XX variant.

Response Object

📚 Specification Link

• description ✅
• headers ✅
  • See Header Object for more details.
• content ✅
  • See Media Type Object for more details.
• links ⛔
  • See Link Object for more details.

Callback Object

📚 Specification Link

As a Callback Object is a container for a Path Item Object, see the Path Item Object for our list of supported components.

Note that we do not currently support making API requests to callback endpoints, they are purely rendered as documentation.

Example Object

📚 Specification Link

• summary ✅
  • If this is not supplied, when rendering Request Body examples we will set this to "Request Example".
• description ⛔
  • We currently do not surface example descriptions anywhere.
• value ✅
• externalValue ⛔
  • We currently do not surface external example values anywhere.

Link Object

📚 Specification Link

🛑

We currently do not support the Link Object.

• operationRef
• operationId
• parameters
• requestBody
• description
• server
  • See Server Object for more details.

Header Object

📚 Specification Link

👍

Where we support headers, and the Header Object, we support everything for headers that we support within the Parameter Object. See Parameter Object for more information.

Tag Object

📚 Specification Link

• name ✅
• description ✅
• externalDocs ✅
  • See External Documentation Object for more details.

When handling tags not only do we ingest them when you upload an OpenAPI definition to create Categories, Pages and Subpages, but we also render tags on your API Reference like so:

Reference Object

📚 Specification Link

Prior to rendering your API documentation all $ref pointers are dereferenced. Additionally, as of OpenAPI 3.1, you can include summary and description fields in addition to the $ref pointer, which will override the summary and description fields of the referenced component. Everything else will be fully deferenced.

Relative schemas ($ref: "Pet.json") and URL references ($ref: "https://example.com/Pet") are not supported on ReadMe and will be rejected on upload. If your schema uses relative schemas or URL references you can instead upload your API definition via rdme and that will bundle all the necessary schemas together into a single payload acceptable for our API.

📘

Note that we currently struggle to handle recursive and circular reference objects. Under certain circumstances in parameters and request bodies we're able to handle a circular reference it’s within an array (like an array of objects).

Schema Object

📚 Specification Link

Properties

• additionalProperties ⚠️
  • Though JSON Schema Specification Wright Draft 00 specifies that when additionalProperties is not present, defaults to true, ReadMe defaults to false for a cleaner UI. If you wish to allow users to add additional properties you should explicitly set this to true.
• allOf ✅
• anyOf ✅
• const ✅
• default ✅
• description ✅
• enum ✅
• exclusiveMaximum ✅
• exclusiveMinimum ✅
• format ✅
  • See Data Types for a list of formats that we support.
• items ✅
• maximum ✅
• maxItems ✅
• maxLength ✅
• maxProperties ✅
• minimum ✅
• minItems ✅
• minLength ✅
• minProperties ⛔
• multipleOf ✅
• not ⛔
• oneOf ✅
• pattern ✅
• patternProperties ⛔
• properties ✅
• required ✅
• title ✅
  • title in a schema associated with a Parameter or Request Body OAS section is prioritized over that section's name property when displaying a label to an end user.
• type ⚠️
  • We support general and mixed type declarations however our API Explorer form system does not support setting null data for mixed non-primitive and non-boolean nullable schemas. For example, ['boolean', 'null'] and ['string', 'null'] are supported but ['array', 'null'] and ['object', 'null'] are not.
• uniqueItems ✅

Fixed Fields

• deprecated ✅
• discriminator ✅
  • See Discriminator Object for more details.
• example ✅
• externalDocs ⛔
  • See External Documentation Object for more details.
• nullable ⚠️
  • Our API Explorer form system does not support setting null data for array, object, or boolean types.
• readOnly ✅
  • Properties marked as readOnly: true are only rendered in the Response Schema section.
• writeOnly ✅
  • Properties marked as writeOnly: true are only rendered in the Request section.
• xml ⛔
  • See XML Object for more details.

JSON Schema Dialects

📘

Unicode regular expressions are only supported with OpenAPI v3.1.x documents and JSON Schema v2020-12. If no JSON Schema dialects are specified, we adhere to the OAS and default to v2020-12 for all OpenAPI v3.1.x documents.

We support the following JSON Schema dialects:

• Draft 4
• 2020-12

Data Types

📚 Specification Link

We support a number of different data types and formats:

† We do not render a date picker for date and date-time due to the lack of wide browser support for datetime-local and RFC 3339.

‡ We do not perform any validation on this value to ensure the value remains unchanged.

Discriminator Object

📚 Specification Link

• propertyName ✅
• mapping ✅

XML Object

📚 Specification Link

🛑

We currently do not support the XML Object.

• name
• namespace
• prefix
• attribute
• wrapped

Security Scheme Object

📚 Specification Link

• type ⚠️
  • We do not support the openIdConnect security type.
  • We do not support the mutualTLS security type that was introduced in OpenAPI 3.1
• description ✅
• name ✅
• in ✅
• scheme ✅
• bearerFormat ⚠️
  • The OpenAPI Specification specifies that this describes how the bearer formatted but since we do not support OAuth Flows that would format the bearer, we currently ignore this.
• flows ⛔
  • We currently do not support traditional OAuth flows for generating tokens, instead preferring you use our JWT authentication flow for supplying us with ready-made tokens for your users. See OAuth Flows Object for more details.
• openIdConnectUrl ⛔
  • We do not support the openIdConnect security type.

OAuth Flows Object

📚 Specification Link

🛑

We currently do not support OAuth Flows anywhere so we currently ignore the OAuth Flows Object. We have plans to support this in the future.

• implicit – OAuth Flow Object
• password – OAuth Flow Object
• clientCredentials – OAuth Flow Object
• authorizationCode – OAuth Flow Object

OAuth Flow Object

📚 Specification Link

🛑

We do not support OAuth Flows anywhere currently so we ignore the OAuth Flow Object. We have plans to support this in the future.

• authorizationUrl
• tokenUrl
• refreshUrl
• scopes

Security Requirement Object

📚 Specification Link

While we only support a subset of Security Scheme Objects, we can support all combinations of those objects. For example we can support multiple headers, one header or OAuth, one query parameter and one header and so on.

Specification Extensions

📚 Specification Link

The OpenAPI specification allows for augmenting certain Objects with custom extensions and we support these, but only our extensions. If you have custom extensions in place for things like AWS API Gateways, they will be ignored.

For the full list of our extensions that we offer and support, see OpenAPI Extensions.