openapi-typesafe

Appearance

Advanced usage ​

Advanced usage and various topics. Interpret this as loose recommendations for most people, and feel free to disregard if it doesn’t work for your setup!

Debugging ​

To enable debugging, set DEBUG=openapi-ts:* as an env var like so:

sh
$ DEBUG=openapi-ts:* npx openapi-typesafe schema.yaml -o my-types.ts

To only see certain types of debug messages, you can set DEBUG=openapi-ts:[scope] instead. Valid scopes are redoc, lint, bundle, and ts.

Debug messages go to stderr, so they do not mix with types written to stdout.

Enum extensions ​

x-enum-varnames can be used to have another enum name for the corresponding value. This is used to define names of the enum items.

x-enum-descriptions can be used to provide an individual description for each value. This is used for comments in the code (like javadoc if the target language is java).

x-enum-descriptions and x-enum-varnames are each expected to be list of items containing the same number of items as enum. The order of the items in the list matters: their position is used to group them together.

Example:

yaml
ErrorCode:
  type: integer
  format: int32
  enum:
    - 100
    - 200
    - 300
  x-enum-varnames:
    - Unauthorized
    - AccessDenied
    - Unknown
  x-enum-descriptions:
    - "User is not authorized"
    - "User has no access to this resource"
    - "Something went wrong"

Will result in:

ts
export enum ErrorCode {
  // User is not authorized
  Unauthorized = 100,
  // User has no access to this resource
  AccessDenied = 200,
  // Something went wrong
  Unknown = 300
}

To generate in this fashion, --enum needs to be specified on the command line.

Alternatively you can use x-enumNames and x-enumDescriptions (NSwag/NJsonSchema).

Styleguide ​

Loose recommendations to improve type generation.

Redocly rules ​

To reduce errors in TypeScript generation, the following built-in rules are recommended to enforce in your Redocly config:

RuleSettingReason
operation-operationId-uniqueerrorPrevents invalid TS generation
operation-parameters-uniqueerrorPrevents missing params
path-not-include-queryerrorPrevents missing params
spec3.0 or 3.1Enables better schema checks

Embrace snake_case in JS ​

Different languages have different preferred syntax styles. To name a few:

  • snake_case
  • SCREAMING_SNAKE_CASE
  • camelCase
  • PascalCase
  • kebab-case

It’s tempting to want to rename API responses into camelCase that most JS styleguides encourage. However, avoid renaming because in addition to being a time sink, it introduces the following maintenance issues:

  • generated types (like the ones produced by openapi-typesafe) now have to be manually typed again
  • renaming has to happen at runtime, which means you’re slowing down your application for an invisible change
  • name transformation utilities have to be built & maintained (and tested!)
  • the API probably needs snake_case for requestBodies anyway, so all that work now has to be undone for every API request

Instead, treat “consistency” in a more holistic sense, recognizing that preserving the API schema as-written is better than adhering to JS style conventions.

Enable noUncheckedIndexedAccess in TSConfig ​

Enable compilerOptions.noUncheckedIndexedAccess in TSConfig (docs) so any additionalProperties key will be typed as T | undefined.

The default behavior of Additional Properties (dictionaries) will generate a type of Record<string, T>, which can very easily produce null reference errors. TypeScript lets you access any arbitrary key without checking it exists first, so it won’t save you from typos or the event a key is just missing.

Be specific in your schema ​

openapi-typesafe will never produce an any type. Anything not explicated in your schema may as well not exist. For that reason, always be as specific as possible. Here’s how to get the most out of additionalProperties:

SchemaGenerated Type
Bad
yaml
type: object
ts
Record<string, never>;
Less Bad
yaml
type: object
additionalProperties: true
ts
Record<string, unknown>;
Best
yaml
type: object
additionalProperties:
  type: string
ts
Record<string, string>;

When it comes to tuple types, you’ll also get better results by representing that type in your schema. Here’s the best way to type out an [x, y] coordinate tuple:

 SchemaGenerated Type
Bad
yaml
type: array
ts
unknown[]
Less Bad
yaml
type: array
items:
  type: number
ts
number[]
Best
yaml
type: array
items:
  type: number
maxItems: 2
minItems: 2

(with --array-length)

— or —

yaml
type: array
items: false
minItems: 2
prefixItems:
  - type: number
  - type: number

(items: false closes the tuple and minItems requires both elements, as the prefix-items fix reads them)

ts
[number, number];

Use oneOf by itself ​

OpenAPI’s composition tools (oneOf/anyOf/allOf) are powerful tools for reducing the amount of code in your schema while maximizing flexibility. TypeScript unions, however, don’t provide XOR behavior, which means they don’t map directly to oneOf. For that reason, it’s recommended to use oneOf by itself, and not combined with other composition methods or other properties. e.g.:

Avoid ​

yaml
Pet:
  type: object
  properties:
    type:
      type: string
      enum:
        - cat
        - dog
        - rabbit
        - snake
        - turtle
    name:
      type: string
  oneOf:
    - $ref: "#/components/schemas/Cat"
    - $ref: "#/components/schemas/Dog"
    - $ref: "#/components/schemas/Rabbit"
    - $ref: "#/components/schemas/Snake"
    - $ref: "#/components/schemas/Turtle"

This generates the following type which mixes both TypeScript unions and intersections. While this is valid TypeScript, it’s complex, and inference may not work as you intended. But the biggest offense is TypeScript can’t discriminate via the type property:

ts
  Pet: ({
    /** @enum {string} */
    type?: "cat" | "dog" | "rabbit" | "snake" | "turtle";
    name?: string;
  }) & (components["schemas"]["Cat"] | components["schemas"]["Dog"] | components["schemas"]["Rabbit"] | components["schemas"]["Snake"] | components["schemas"]["Turtle"]);

Prefer ​

yaml
Pet:
  oneOf:
    - $ref: "#/components/schemas/Cat"
    - $ref: "#/components/schemas/Dog"
    - $ref: "#/components/schemas/Rabbit"
    - $ref: "#/components/schemas/Snake"
    - $ref: "#/components/schemas/Turtle"
PetCommonProperties:
  type: object
  properties:
    name:
      type: string
Cat:
  allOf:
    - "$ref": "#/components/schemas/PetCommonProperties"
  properties:
    type:
      type: string
      enum:
        - cat

The resulting generated types are not only simpler; TypeScript can now discriminate using type (notice Cat has type with a single enum value of "cat").

ts
Pet: components["schemas"]["Cat"] | components["schemas"]["Dog"] | components["schemas"]["Rabbit"] | components["schemas"]["Snake"] | components["schemas"]["Turtle"];
Cat: { type?: "cat"; } & components["schemas"]["PetCommonProperties"];

Note: you optionally could provide discriminator.propertyName: "type" on Pet (docs) to automatically generate the type key, but is less explicit.

While the schema permits you to use composition in any way you like, it’s good to always take a look at the generated types and see if there’s a simpler way to express your unions & intersections. Limiting the use of oneOf is not the only way to do that, but often yields the greatest benefits.

Discriminator values ​

A discriminator gives each member schema a value of its property. A mapping entry names it; a member that no entry names gets its schema name, as the Discriminator Object says. If the member's property has an enum or const that does not list that value, no value of the member matches the discriminator, and where the generator adds the value to the member the property is never. openapi-typesafe warns about each such member:

yaml
Item:
  oneOf: [{ $ref: "#/components/schemas/Episode" }]
  discriminator: { propertyName: type } # Episode gets the value "Episode"
Episode:
  type: object
  properties:
    type: { type: string, enum: [episode] } # does not list "Episode"

Add a mapping entry for the value the property allows (mapping: { episode: "#/components/schemas/Episode" }).

A member is a schema that the discriminator's oneOf, anyOf or mapping names, or one that allOfs the owner, also through other schemas (Lion: { allOf: [Cat] }, Cat: { allOf: [Pet] }). Below a schema with its own discriminator of the property, the schemas are that one's members. With --fix allof-discriminated-union, a schema that allOfs a union which neither lists nor maps it reuses the union and gets no value, so it is no member.

Enum values arrays ​

--enum-values exports each enum's values as an array typed by the place of its schema in the generated types:

ts
export const petStatusValues: ReadonlyArray<FlattenedDeepRequired<components>["schemas"]["Pet"]["status"]> = ["available", "sold"];

Where that type cannot hold the values, the array is typed by its own values instead, so the file compiles (ReadonlyArray<"available" | "sold">):

  • the place has no type of its own: a schema under definitions, an allOf member, a positional operation parameter, or a property of a schema whose type is unknown (an anyOf with a variant that has only required), whether the property is the schema's own or one of another anyOf variant;
  • an anyOf member is an array of the enum and another member is not an array;
  • the enum is empty (enum: []): its type is never, so the array is readonly never[];
  • --read-write-markers wraps the property in $Read<T> or $Write<T>, an object type;
  • the schema contradicts itself: an allOf of enums with different values, or a discriminator value that the property enum does not list. The type there admits fewer values, or none; this case also prints a warning that names the array and the values.

Every other array keeps its type.

JSONSchema $defs caveats ​

JSONSchema $defs can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:

yaml
components:
  schemas:
    DefType:
      type: object # an object schema keeps its $defs
      $defs:
        myDefType:
          type: string
    MyType:
      type: object
      properties:
        myType:
          $ref: "#/components/schemas/DefType/$defs/myDefType"

This will transform into the following TypeScript:

ts
export interface components {
  schemas: {
    DefType: {
      $defs?: {
        myDefType: string;
      };
    };
    MyType: {
      myType?: NonNullable<components["schemas"]["DefType"]["$defs"]>["myDefType"]; // works
    };
  };
}

However, this won’t:

yaml
components:
  schemas:
    DefType:
      type: string # a string schema loses its $defs
      $defs:
        myDefType:
          type: string
    MyType:
      properties:
        myType:
          $ref: "#/components/schemas/DefType/$defs/myDefType"

Because it will transform into:

ts
export interface components {
  schemas: {
    DefType: string;
    MyType: {
      myType?: NonNullable<components["schemas"]["DefType"]["$defs"]>["myDefType"]; // Error: Property '$defs' does not exist on type 'String'.
    };
  };
}

So be wary about where you define $defs as they may go missing in your final generated types.

TIP

When in doubt, you can always define $defs at the root schema level.

Untrusted documents ​

A document can refer to other files and URLs with $ref, and the generator loads them. By default it loads any local file it can read and any http(s) URL it can reach, as openapi-typescript does. For a document you did not write (from a vendor, a URL or a user), limit both:

bash
npx openapi-typesafe ./vendor/openapi.yaml -o ./src/api/schema.d.ts \
  --local-ref-root ./vendor --remote-ref-hosts api.vendor.example
  • --local-ref-root (localRefRoot in the Node API): local $ref files must be in this directory or below it. A relative path is relative to the working directory; the flag without a value means the working directory. Links are followed before the check, so a link inside the directory that points outside it is refused too.
  • --remote-ref-hosts (remoteRefHosts): remote $ref documents must come from these hosts, written as name (any port) or name:port. Hosts are compared as URLs write them, so case, a trailing dot, Unicode names, IPv6 with or without brackets (::1, [::1]:8080) and a default port (api.example.com:443) all match. An empty list (--remote-ref-hosts=) allows no remote $ref. Each redirect is checked against the list and at most 20 are followed. A listed name is trusted: it is not checked again after DNS resolution.
  • Headers from your Redocly config go only to the URLs their patterns match, over HTTPS or to this machine unless a pattern starts with http://; each redirect hop gets only the headers its own URL matches (Auth). This holds with or without the two flags.
  • In redocly.yaml, an API can set its own limits as local-ref-root and remote-ref-hosts under x-openapi-ts; they replace the flags for that API (see Multiple schemas).
  • The document you pass to the generator is never limited, only what it refers to.
  • A remote document may refer only to other http(s) URLs. A $ref in it that names a local file (file:///…, or C:/…, which a URL base turns into a drive-letter path) is always refused.

A refused $ref fails with SCHEMA_REF_FORBIDDEN (CLI exit code 3); err.details has the ref and the reason (outside-local-root, host-not-allowed, local-ref-from-remote, or too-many-remote-documents from Limits). The threat model explains the risks (T3, T4).

Limits ​

openapi-typesafe fails with a typed error (err.code, CLI exit code 3) instead of crashing or hanging when a document reaches one of these limits.

LimitWhat happensError code
A YAML or JSON file nested more than 100 levels deepThe YAML parser stops. A document passed as an object or as JSON text skips this limitSCHEMA_PARSE_FAILED
About 550 levels of inline schemas, or a chain of about 900 $refs where each schema refers to the nextThe call stack runs out. The numbers are for the default Node.js stack and vary a little between runs and runtimesSCHEMA_TOO_DEEP
A $ref that points at itself, or two $refs that point at each other, with no schema in betweenThe cycle has no typeSCHEMA_REF_INVALID
A key named hasOwnProperty, isPrototypeOf, propertyIsEnumerable, toLocaleString, valueOf or one of the __define… / __lookup… methods, where the schema loader reads keys, or a constructor entry whose value has a string name (a security scheme or header named constructor)The schema loader (Redocly 1.x) cannot read it; the error lists every such keySCHEMA_KEY_UNSUPPORTED
YAML aliases (*name) that expand a file to more than 1,000,000 nodes and to more than 100 times its written size (a "billion laughs" document)The file is refused right after parsing, before anything walks itSCHEMA_PARSE_FAILED
More than 10,000 remote documents in one run (each document that refers to new URLs, without end)The next remote document is refused before it is fetched. At most 16 remote documents are fetched at the same timeSCHEMA_REF_FORBIDDEN (reason too-many-remote-documents)
A remote $ref or remote document that does not answer, or does not finish sending its body, within 60 secondsThe fetch stops. A customFetch in your Redocly config replaces this limitSCHEMA_INVALID (a $ref) or SCHEMA_LOAD_FAILED (the document)

Cyclic schemas are fine when the cycle goes through an object property (Node: { properties: { next: { $ref: Node } } }): they generate recursive types. A cycle with no object on it, such as two arrays of each other or two allOfs of each other, generates types that TypeScript rejects with “is referenced directly or indirectly in its own type annotation”, as in openapi-typescript. The common case is a JSON value schema whose anyOf or oneOf holds an array of itself (JSONValue: anyOf: [string, number, { type: array, items: { $ref: JSONValue } }]). It gives JSONValue: components["schemas"]["JSONValue"][] | string | number, and TypeScript defers an array of itself only in a type alias, not in an interface property (TS2502). An array that sits in an object property ({ type: object, properties: { items: { type: array, … } } }) is fine.

Names need no care: reserved words (class, default, constructor), TypeScript global names, __proto__, Unicode, quotes, backslashes and line breaks in schema, property, enum, path and parameter names all generate valid TypeScript.

Released under the MIT License. Built on openapi-typescript, openapi-fetch and openapi-react-query.