OpenAPI support

This page lists what oasis-gen accepts from a document and what it does with each feature. The support levels mean the following:

• Supported: the feature affects the generated client.
• Ignored: the feature is accepted but does not affect the generated client.
• Rejected: the feature stops generation with an error.
• Not supported: the feature is handled only as noted, or not at all.

Versions

Version	Support
OpenAPI 3.2	Supported
OpenAPI 3.1	Supported; treated exactly like 3.2
OpenAPI 3.0	Supported, with the differences below
Swagger 2.0 (swagger: "2.0")	Not supported

In an OpenAPI 3.0 document, these keywords are handled as follows:

Keyword	Handling
nullable: true	Adds null to the type. On an enum, null is added even if the list omits it. Other generators read it this way, although under 3.0.3 itself such an enum still disallows null
nullable: true next to a $ref, or on an allOf with one $ref	Adds null to the referenced type
Other keywords next to a $ref	Applied, as in 3.1 and later, although 3.0 says to ignore them: { $ref: Base, properties: {...} } is Base & {...}
type: string, format: binary	Raw binary, read as a schema without a type: unknown, or Blob in a multipart body or a text/* response
type: string, format: byte	Base64 text, read as contentEncoding: base64: a string, sent as an application/octet-stream multipart part
example, a boolean exclusiveMinimum	Ignored

nullable in a 3.1 or 3.2 document is rejected, because those versions of the specification would silently ignore it. Use type: [..., "null"] instead.

Documents

Feature	Support	Notes
JSON and YAML	Supported	From a file, or from stdin with -
$refs to other local files	Supported	Whole documents or fragments, resolved relative to the referencing document
$self, and $id and $anchor in schemas	Supported	A $self URI such as https://api.example.com/openapi/root.yaml is mapped onto the file's own directory, so schemas/pet.yaml next to it is found locally
components.mediaTypes and $refs to them	Supported
Component names other than ASCII letters, digits, ., - and _	Rejected	The specification limits them to ^[a-zA-Z0-9\.\-_]+$
Remote $refs, and URLs as input	Not supported	https://... URIs that do not map onto a local file

Schemas from other files get type aliases of their own, but only component schemas are exported and listed in components (see Schemas).

Generate only from documents you trust: oasis-gen reads any local file that a $ref points to, wherever it is.

Schemas

See Schemas for the TypeScript type that each keyword becomes.

Feature	Support	Notes
JSON Schema 2020-12	Supported	type arrays, const, enum, allOf, oneOf, anyOf, prefixItems, minItems, additionalProperties, patternProperties, propertyNames (as a list of names), $ref with sibling keywords, and readOnly and writeOnly (see Strict types)
Recursive schemas	Supported	Through properties, arrays, and additionalProperties, including $refs into $defs and other locations outside components.schemas
discriminator on oneOf or anyOf	Supported	Explicit and implicit mappings, and defaultMapping
Subtypes listed in the parent's oneOf, each extending it with allOf	Supported	See Subtypes
Other cycles through $ref, allOf, oneOf or anyOf alone	Rejected	Cycles with no object or array in between
discriminator on an allOf parent	Not supported	The parent is not turned into a union of its children
$dynamicRef	Not supported	Typed as unknown

Operations

Feature	Support	Notes
get, put, post, delete, options, head, patch, trace	Supported
query (the HTTP QUERY method)	Supported
additionalOperations	Supported	Custom methods such as LINK
Some additionalOperations names	Rejected	delete, get, head, options, post, and put regardless of case, and PATCH, TRACE, and QUERY in uppercase, because fetch would send them as the same methods as the fixed fields; also with and then, which the client reserves
Callbacks and webhooks	Not supported

Parameters

Location	Styles	Notes
query	form, deepObject	allowReserved is supported. spaceDelimited and pipeDelimited are rejected
path	simple	label and matrix are rejected
header	simple
cookie	form (percent-encoded), cookie (sent as-is)	Exploded values are joined with ; for both styles, because the specification rules out & for cookies
querystring	Supported	Typed and encoded by its media type; see querystring parameters

Every style supports explode. Parameters with content instead of a schema are supported. A JSON query parameter is typed from its schema and serialized as JSON. Other parameters with content are passed as strings that are already serialized.

Cookie parameters and cookie API keys are sent as a Cookie header, which browsers ignore in fetch. They work in Node and Bun.

Request and response bodies

See Request bodies and Response bodies for how each media type is typed and decoded.

Feature	Support	Notes
Sequential media types and itemSchema	Supported	JSON Lines, NDJSON, JSON text sequences, and server-sent events, streamed as async iterables
multipart/form-data request bodies	Supported	Typed by the schema and sent as FormData; see Form bodies
Other multipart request bodies, such as multipart/mixed	Not supported	Passed as a Blob the caller builds, whose type gives the media type with its boundary
Encoding Object (encoding)	Supported	contentType, style, explode, and allowReserved. FormData cannot send part headers or nested parts, so optional headers are left out, and a required header or a multipart part is rejected
prefixEncoding, itemEncoding	Not supported	They apply only to other multipart media types
Typed response headers	Not supported

Servers and security

Feature	Support	Notes
servers at the top level, on path items, and on operations	Supported	Variables are set to their defaults; see Servers and baseUrl
Security schemes	Supported	apiKey, http, oauth2, openIdConnect, and mutualTLS, through auth
OAuth2 flows	Not supported	You obtain tokens yourself