OpenAPI Schema Conversion#

Kubb's adapter-oas package converts OpenAPI/JSON Schema objects into a language-neutral AST before any code generator runs. The conversion is a multi-step pipeline: a rule table selects the right converter, converter functions build AST nodes, format-mapping constants translate OAS format strings to Kubb schema types, and a rich set of AST node types preserves semantic meaning for downstream generators.

Architecture Overview#

OAS SchemaObject
      │
      ▼
schemaRules (ordered rule table) ← parseSchema.ts
      │ first matching rule wins
      ▼
converter function (scalar / structural / composition)
      │ produces
      ▼
ast.SchemaNode (one of ~15 typed variants)
      │
      ▼
downstream plugin (plugin-ts, plugin-zod, …)

The rule table, converter modules, and AST node types are each in a different package; the constants file ties them together.

1. Rule Table — parseSchema.ts#

schemaRules is an ordered Array<SchemaRule> where each entry has a match predicate and a convert function. The first rule whose match returns true wins; no fall-through occurs.

Priority order 1:

1. $ref → convertRef
2. allOf → convertAllOf
3. oneOf / anyOf → convertUnion
4. const → convertConst
5. format (handled or date-ish with dateType !== false) → convertFormat
6. Binary (contentMediaType: application/octet-stream) → convertBinary
7. OAS 3.1 multi-type array → convertMultiType
8. Implicit string (has minLength/maxLength/pattern but no type) → convertString
9. Implicit number (has minimum/maximum but no type) → convertNumeric
10. enum → convertEnum
11. Object / properties → convertObject
12. prefixItems → convertTuple
13. Array → convertArray
14. Explicit type: 'string' | 'number' | 'integer' | 'boolean' | 'null'

Each converter receives a ConvertContext 2, which combines the pre-computed SchemaContext (normalized type, options, defaults) with ConverterDeps (a ParseFn for recursion, the document, and the $ref service).

2. Converter Functions#

Converters live in three files under packages/adapter-oas/src/emit/converters/:

The key format converter is convertFormat, which handles three classes:

• int64 → bigint or integer depending on options.integerType 3
• Date/time (date-time, date, time) → dispatches to getDateType, which honors options.dateType to produce datetime, date, or time nodes with offset/local/representation flags
• Everything else → looks up formatMap via getSchemaType, then emits a typed node; url, uuid, and email also carry min/max length from minLength/maxLength 4

3. Format Mapping — constants.ts#

formatMap is the static lookup table from OAS format strings to Kubb SchemaType values. It only lists formats whose AST type differs from the raw OAS type:

Formats that require runtime option awareness (int64, date-time, date, time) are not in formatMap; they are listed separately in specialCasedFormats and handled directly in convertFormat.

isHandledFormat gates the format rule in schemaRules: it returns true for any formatMap entry or any specialCasedFormat. Formats not in either set fall back to the base type, and the parser emits a KUBB_UNSUPPORTED_FORMAT diagnostic.

4. AST Node Types — packages/ast/src/nodes/schema.ts#

The full SchemaType union 5 has three layers:

• PrimitiveSchemaType — string, number, integer, bigint, boolean, null, any, unknown, void, never, object, array, date
• ComplexSchemaType — tuple, union, intersection, enum
• SpecialSchemaType — ref, datetime, time, uuid, email, url, ipv4, ipv6, blob

Dedicated semantic node types for string formats 6:

The SchemaNodeBase shared by all nodes stores primitive — the underlying JavaScript primitive type (e.g., uuid nodes carry primitive: 'string') — enabling generators to fall back gracefully when they don't support a given special type 7.

The factory function createSchema is the single entry point for constructing any SchemaNode. It automatically fills primitive from the TYPE_TO_PRIMITIVE map 8.

5. Parser Options & Defaults#

DEFAULT_PARSER_OPTIONS provides the baseline ast.ParserOptions:

These defaults are applied in parser.ts and adapter.ts when callers don't supply explicit options.

Key Files#