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 under OpenAPI 3.1, since we currently don't support webhooks or API definitions with just components you must have `
paths
` present to upload an API definition into ReadMe.
`
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
` âWe use this data to determine what version of your docs to place your API definition into when you upload it. See [Versions](đï»ż) for more information.
## 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
` â`
style
` â`
explode
` â`
allowReserved
` â`
schema
` âSee [Schema Object](đï»ż) for more details.
`
example
` â`
examples
` â`
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.
### Style Values
đ [Specification Link](đï»ż)ï»ż
Support for parameter `style
` serialization:
`style ` | Data type | `explode ` | Path | Query, `multipart/form-data ` | Cookie | Header |
matrix | primitive | `true ` | â | - | - | - |
matrix | primitive | `false ` | â | - | - | - |
matrix | array | `true ` | â | - | - | - |
matrix | array | `false ` | â | - | - | - |
matrix | object | `true ` | â | - | - | - |
matrix | object | `false ` | â | - | - | - |
label | primitive | `true ` | â | - | - | - |
label | primitive | `false ` | â | - | - | - |
label | array | `true ` | â | - | - | - |
label | array | `true ` | â | - | - | - |
label | object | `true ` | â | - | - | - |
label | object | `true ` | â | - | - | - |
form | primitive | `true ` | - | â | â | ï»ż |
form | primitive | `false ` | - | â | â | ï»ż |
form | array | `true ` | - | â | â | ï»ż |
form | array | `false ` | - | â | â | ï»ż |
form | object | `true ` | - | â | â | ï»ż |
form | object | `false ` | - | â | â | ï»ż |
simple | array | `true ` | â | - | - | â |
simple | array | `false ` | â | - | - | â |
spaceDelimited | array | `true ` | - | â | - | - |
spaceDelimited | array | `false ` | - | â | - | - |
spaceDelimited | object | `true ` | - | â | - | - |
spaceDelimited | object | `false ` | - | â | - | - |
spaceDelimited | query | `true ` | â ïž | â ïž | â ïž | â ïž |
spaceDelimited | query | `false ` | â ïž | â ïž | â ïž | â ïž |
pipeDelimited | array | `true ` | - | â | - | - |
pipeDelimited | array | `false ` | - | â | - | - |
pipeDelimited | object | `true ` | - | â | - | - |
pipeDelimited | object | `false ` | - | â | - | - |
pipeDelimited | query | `true ` | â ïž | â ïž | â ïž | â ïž |
pipeDelimited | query | `false ` | â ïž | â ïž | â ïž | â ïž |
deepObject | object | `true ` | - | â
(including arrays of objects, serialized using the [`qs `](đï»ż) module) | - | - |
deepObject | object | `false ` | - | â | - | - |
ï»ż
`
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](đï»ż).
Code | Description |
1XX | Informational |
100 | Continue |
101 | Switching Protocols |
102 | Processing |
103 | Early Hints |
2XX | Success |
200 | OK |
201 | Created |
202 | Accepted |
203 | Non-Authoritative Information |
204 | No Content |
205 | Reset Content |
206 | Partial Content |
207 | Multi-Status |
208 | Already Reported |
218 | This is fine |
226 | IM Used |
3XX | Redirection |
300 | Multiple Choices |
301 | Moved Permanently |
302 | Found |
303 | See Other |
304 | Not Modified |
305 | Use Proxy |
306 | Switch Proxy |
307 | Temporary Redirect |
308 | Permanent Redirect |
4XX | Client Error |
400 | Bad Request |
401 | Unauthorized |
402 | Payment Required |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
407 | Proxy Authentication Required |
408 | Request Timeout |
409 | Conflict |
410 | Gone |
411 | Length Required |
412 | Precondition Failed |
413 | Payload Too Large |
414 | URI Too Long |
415 | Unsupported Media Type |
416 | Range Not Satisfiable |
417 | Expectation Failed |
418 | I'm a teapot |
419 | Page Expired |
420 | Enhance Your Calm |
421 | Misdirected Request |
422 | Unprocessable Entity |
423 | Locked |
424 | Failed Dependency |
425 | Too Early |
426 | Upgrade Required |
428 | Precondition Required |
429 | Too Many Requests |
430 | Request Header Fields Too Large |
431 | Request Header Fields Too Large |
440 | Login Time-out |
444 | No Response |
449 | Retry With |
450 | Blocked by Windows Parental Controls |
451 | Unavailable For Legal Reasons |
494 | Request Header Too Large |
495 | SSL Certificate Error |
496 | SSL Certificate Required |
497 | HTTP Request Sent to HTTPS Port |
498 | Invalid Token |
499 | Client Error |
5XX | Server Error |
500 | Internal Server Error |
501 | Not Implemented |
502 | Bad Gateway |
503 | Service Unavailable |
504 | Gateway Timeout |
505 | HTTP Version Not Supported |
506 | Variant Also Negotiates |
507 | Insufficient Storage |
508 | Loop Detected |
509 | Bandwidth Limit Exceeded |
510 | Not Extended |
511 | Network Authentication Required |
520 | Web Server Returned an Unknown Error |
521 | Web Server Is Down |
522 | Connection Timed Out |
523 | Origin Is Unreachable |
524 | A Timeout Occurred |
525 | SSL Handshake Failed |
526 | Invalid SSL Certificate |
527 | Railgun Error |
529 | Site is Overloaded |
530 | Site is Frozen |
598 | Network Read Timeout Error |
## 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 just rendered as pure 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
` â`
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
` â`
uniqueItems
` â
### Fixed Fields
`
nullable
` â`
discriminator
` âSee [Discriminator Object](đï»ż) for more details.
`
readOnly
` â`
writeOnly
` â`
xml
` âSee [XML Object](đï»ż) for more details.
`
externalDocs
` âSee [External Documentation Object](đï»ż) for more details.
`
example
` â`
deprecated
` â
### 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:
Type | Format | Comments |
`boolean ` | ï»ż | ï»ż |
`integer ` | ï»ż | ï»ż |
`integer ` | `int8 ` | ï»ż |
`integer ` | `int16 ` | ï»ż |
`integer ` | `int32 ` | ï»ż |
`integer ` | `int64 ` | ï»ż |
`integer ` | `uint8 ` | ï»ż |
`integer ` | `uint16 ` | ï»ż |
`integer ` | `uint32 ` | ï»ż |
`integer ` | `uint64 ` | ï»ż |
`number ` | ï»ż | ï»ż |
`number ` | `float ` | ï»ż |
`number ` | `double ` | ï»ż |
`string ` | ï»ż | ï»ż |
`string ` | `binary ` | Will render out a [file input](đï»ż). |
`string ` | `blob ` | Will render out a [textarea](đï»ż). |
`string ` | `byte ` | ⥠|
`string ` | `date ` | â |
`string ` | `dateTime ` | â |
`string ` | `date-time ` | â |
`string ` | `duration ` | ï»ż |
`string ` | `html ` | Will render out a [textarea](đï»ż). ⥠|
`string ` | `json ` | Will render out a [textarea](đï»ż). ⥠|
`string ` | `password ` | Will render out a [password field](đï»ż) to mask all input. |
`string ` | `timestamp ` | ï»ż |
`string ` | `uri ` | ⥠|
`string ` | `url ` | ⥠|
`string ` | `uuid ` | ⥠|
â 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](đï»ż).