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: RDMDRDMD - Our custom ReadMe-flavored Markdown engine. It's based on remark (meaning it supports all the Markdown syntax you know and love) and adds some custom syntax to support ReadMe features such as variables, glossary (i.e. what you're reading right now!), and emoji! You can read more about RDMD in our docs: rdmd.readme.io

OpenAPI Object

πŸ“š Specification Link

Info Object

πŸ“š Specification Link

  • title βœ…
  • summary β›”
    • summary is new to OpenAPI 3.1.
  • description β›”
  • termsOfService β›”
  • contact β›”
  • license β›”
  • 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

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 dereferenceddereferenced - The act of dereferencing all `$ref` pointers within an OpenAPI definition, replacing each reference with the value or schema that it resolves to. prior to rendering.

Paths Object

πŸ“š Specification Link

πŸ‘

We support the Path Object because we wouldn't offer an API ReferenceAPI Reference - The API reference section of your ReadMe documentation contains information about each of your endpoints and the data that is sent and received. Users can construct and send API requests and view code samples in a language of their choiceβ€”all without leaving the docs! without them. πŸ˜€

Path Item Object

πŸ“š Specification Link

  • $ref βœ…
    • All $ref pointers are dereferenceddereferenced - The act of dereferencing all `$ref` pointers within an OpenAPI definition, replacing each reference with the value or schema that it resolves to. 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

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 βœ…
  • example βœ…
  • examples βœ…
  • content ⚠️
    • Though we support content, the API ReferenceAPI Reference - The API reference section of your ReadMe documentation contains information about each of your endpoints and the data that is sent and received. Users can construct and send API requests and view code samples in a language of their choiceβ€”all without leaving the docs! 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:

styleData typeexplodePathQuery, multipart/form-dataCookieHeader
matrixprimitivetrueβœ…---
matrixprimitivefalseβœ…---
matrixarraytrueβœ…---
matrixarrayfalseβœ…---
matrixobjecttrueβœ…---
matrixobjectfalseβœ…---
labelprimitivetrueβœ…---
labelprimitivefalseβœ…---
labelarraytrueβœ…---
labelarraytrueβœ…---
labelobjecttrueβœ…---
labelobjecttrueβœ…---
formprimitivetrue-βœ…βœ…
formprimitivefalse-βœ…βœ…
formarraytrue-βœ…βœ…
formarrayfalse-βœ…βœ…
formobjecttrue-βœ…βœ…
formobjectfalse-βœ…βœ…
simplearraytrueβœ…--βœ…
simplearrayfalseβœ…--βœ…
spaceDelimitedarraytrue-βœ…--
spaceDelimitedarrayfalse-βœ…--
spaceDelimitedobjecttrue-βœ…--
spaceDelimitedobjectfalse-β›”--
spaceDelimitedquerytrue⚠️⚠️⚠️⚠️
spaceDelimitedqueryfalse⚠️⚠️⚠️⚠️
pipeDelimitedarraytrue-βœ…--
pipeDelimitedarrayfalse-βœ…--
pipeDelimitedobjecttrue-βœ…--
pipeDelimitedobjectfalse-β›”--
pipeDelimitedquerytrue⚠️⚠️⚠️⚠️
pipeDelimitedqueryfalse⚠️⚠️⚠️⚠️
deepObjectobjecttrue-βœ…--
deepObjectobjectfalse-βœ…--

🚧

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 ReferenceAPI Reference - The API reference section of your ReadMe documentation contains information about each of your endpoints and the data that is sent and received. Users can construct and send API requests and view code samples in a language of their choiceβ€”all without leaving the docs! 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.

CodeDescription
1XXInformational
100Continue
101Switching Protocols
102Processing
103Early Hints
2XXSuccess
200OK
201Created
202Accepted
203Non-Authoritative Information
204No Content
205Reset Content
206Partial Content
207Multi-Status
208Already Reported
218This is fine
226IM Used
3XXRedirection
300Multiple Choices
301Moved Permanently
302Found
303See Other
304Not Modified
305Use Proxy
306Switch Proxy
307Temporary Redirect
308Permanent Redirect
4XXClient Error
400Bad Request
401Unauthorized
402Payment Required
403Forbidden
404Not Found
405Method Not Allowed
406Not Acceptable
407Proxy Authentication Required
408Request Timeout
409Conflict
410Gone
411Length Required
412Precondition Failed
413Payload Too Large
414URI Too Long
415Unsupported Media Type
416Range Not Satisfiable
417Expectation Failed
418I'm a teapot
419Page Expired
420Enhance Your Calm
421Misdirected Request
422Unprocessable Entity
423Locked
424Failed Dependency
425Too Early
426Upgrade Required
428Precondition Required
429Too Many Requests
430Request Header Fields Too Large
431Request Header Fields Too Large
440Login Time-out
444No Response
449Retry With
450Blocked by Windows Parental Controls
451Unavailable For Legal Reasons
494Request Header Too Large
495SSL Certificate Error
496SSL Certificate Required
497HTTP Request Sent to HTTPS Port
498Invalid Token
499Client Error
5XXServer Error
500Internal Server Error
501Not Implemented
502Bad Gateway
503Service Unavailable
504Gateway Timeout
505HTTP Version Not Supported
506Variant Also Negotiates
507Insufficient Storage
508Loop Detected
509Bandwidth Limit Exceeded
510Not Extended
511Network Authentication Required
520Web Server Returned an Unknown Error
521Web Server Is Down
522Connection Timed Out
523Origin Is Unreachable
524A Timeout Occurred
525SSL Handshake Failed
526Invalid SSL Certificate
527Railgun Error
529Site is Overloaded
530Site is Frozen
598Network Read Timeout Error

Response Object

πŸ“š Specification Link

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

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:

Tags in the API ReferenceTags in the API Reference

Reference Object

πŸ“š Specification Link

Prior to rendering your API documentation all $ref pointers are dereferenceddereferenced - The act of dereferencing all `$ref` pointers within an OpenAPI definition, replacing each reference with the value or schema that it resolves to.. 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

  • type βœ…
  • allOf βœ…
  • oneOf βœ…
  • anyOf βœ…
  • not β›”
  • items βœ…
  • 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.
  • description βœ…
  • format βœ…
    • See Data Types for a list of formats that we support.
  • default βœ…
  • 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.
  • multipleOf βœ…
  • maximum βœ…
  • exclusiveMaximum βœ…
  • minimum βœ…
  • exclusiveMinimum βœ…
  • maxLength βœ…
  • minLength βœ…
  • pattern βœ…
  • maxItems βœ…
  • minItems βœ…
  • uniqueItems βœ…
  • maxProperties βœ…
  • minProperties β›”
  • required βœ…
  • enum βœ…

Fixed Fields

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:

Data Types

πŸ“š Specification Link

We support a number of different data types and formats:

TypeFormatComments
boolean
integer
integerint8
integerint16
integerint32
integerint64
integeruint8
integeruint16
integeruint32
integeruint64
number
numberfloat
numberdouble
string
stringbinaryWill render out a file input.
stringblobWill render out a textarea.
stringbyte‑
stringdate†
stringdateTime†
stringdate-time†
stringduration
stringhtmlWill render out a textarea. ‑
stringjsonWill render out a textarea. ‑
stringpasswordWill render out a password field to mask all input.
stringtimestamp
stringuri‑
stringurl‑
stringuuid‑

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

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.


Did this page help you?