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: <<glossary: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](🔗)

  • Though this is optional as defined by OpenAPI 3.1, you must have `paths` present to upload an API definition into ReadMe. This is because ReadMe currently doesn't support webhooks or API definitions that exclusively contain components.

• `webhooks` - Map containing [Path Item Object](🔗) and/or [Reference Object](🔗)

  • `webhooks` is new to OpenAPI 3.1. We currently do not support Webhooks. ⛔

• `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.

• `description` ⛔

• `termsOfService` ⛔

• `contact` ⛔

  • See [Contact Object](🔗) for more details.

• `license` ⛔

  • See [License Object](🔗) for more details.

• `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](🔗)

🛑



We currently do not surface the `Contact Object` anywhere within your documentation.

• `name`

• `url`

• `email`

## License Object

📚 [Specification Link](🔗)

🛑



We currently do not surface the `License Object` anywhere within your documentation.

• `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 <<glossary: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 <<glossary:API Reference>> without them. 😀

## Path Item Object

📚 [Specification Link](🔗)

• `$ref` ✅

  • All `$ref` pointers are <<glossary: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:

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

🚧



`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 <<glossary: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 <<glossary: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 like `['array', 'null']`, `['object', 'null']`, or `['boolean', 'null']`.

• `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` ✅

• `writeOnly` ✅

• `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.