@kubb/adapter-oas 5.0.0-beta.3 → 5.0.0-beta.31

package/src/parser.ts

@@ -1,18 +1,17 @@
-import { URLPath } from '@internals/utils'
+import { pascalCase, URLPath } from '@internals/utils'
 import { ast } from '@kubb/core'
 import BaseOas from 'oas'
 import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, SCHEMA_REF_PREFIX, typeOptionMap } from './constants.ts'
-import { isDiscriminator, isNullable, isReference } from './guards.ts'
-import { resolveRef } from './refs.ts'
+import { oasDialect, type OasDialect } from './dialect.ts'
 import {
   buildSchemaNode,
   flattenSchema,
   getDateType,
-  getMediaType,
   getParameters,
   getPrimitiveType,
   getRequestBodyContentTypes,
   getRequestSchema,
+  getResponseBodyContentTypes,
   getResponseSchema,
   getSchemas,
   getSchemaType,
@@ -30,6 +29,16 @@ export type OasParserContext = {
   contentType?: ContentType
 }
 
+/**
+ * The object returned by {@link createSchemaParser}.
+ * Contains parser functions bound to a specific document.
+ */
+export type SchemaParser = {
+  parseSchema: (entry: { schema: SchemaObject; name?: string | null }, options?: Partial<ast.ParserOptions>) => ast.SchemaNode
+  parseOperation: (options: ast.ParserOptions, operation: Operation) => ast.OperationNode
+  parseParameter: (options: ast.ParserOptions, param: Record<string, unknown>) => ast.ParameterNode
+}
+
 /**
  * Pre-computed per-schema context passed to every schema converter.
  *
@@ -50,6 +59,13 @@ type SchemaContext = {
   options: ast.ParserOptions
 }
 
+/**
+ * One entry in this adapter's schema-dispatch table — a {@link ast.DispatchRule} specialized
+ * to OAS schema context and Kubb `SchemaNode` output. See {@link ast.dispatch} for the contract
+ * a future adapter (e.g. AsyncAPI) follows: define a context type and an ordered rules table.
+ */
+type SchemaRule = ast.DispatchRule<SchemaContext, ast.SchemaNode>
+
 /**
  * Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
  *
@@ -76,9 +92,9 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
  * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
  * made possible by hoisting of function declarations.
  *
- * @note Not exported; called internally by `parseOas()` and `parseSchema()`.
+ * @internal
  */
-function createSchemaParser(ctx: OasParserContext) {
+export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect = oasDialect) {
   const document = ctx.document
 
   // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
@@ -89,6 +105,20 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   const resolvingRefs = new Set<string>()
 
+  /**
+   * Cache of already-resolved `$ref` schemas within this parser instance.
+   *
+   * Without this, the same referenced schema (e.g. `customer`) is fully re-expanded
+   * every time it appears as a `$ref` in a different parent schema. In heavily
+   * cross-referenced specs like Stripe (~1 400 schemas), this causes exponential
+   * blowup — `customer` alone may be referenced from dozens of top-level schemas,
+   * each triggering a fresh recursive expansion of its entire sub-tree.
+   *
+   * Memoizing by `$ref` path reduces the overall work from O(2^depth) to O(N)
+   * where N is the number of unique schema names.
+   */
+  const resolvedRefCache = new Map<string, ast.SchemaNode | null>()
+
   /**
    * Converts a `$ref` schema into a `RefSchemaNode`.
    *
@@ -98,19 +128,23 @@ function createSchemaParser(ctx: OasParserContext) {
    * Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
    */
   function convertRef({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): ast.SchemaNode {
-    let resolvedSchema: ast.SchemaNode | undefined
+    let resolvedSchema: ast.SchemaNode | null = null
     const refPath = schema.$ref
     if (refPath && !resolvingRefs.has(refPath)) {
-      try {
-        const referenced = resolveRef<SchemaObject>(document, refPath)
-        if (referenced) {
-          resolvingRefs.add(refPath)
-          resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
-          resolvingRefs.delete(refPath)
+      if (!resolvedRefCache.has(refPath)) {
+        try {
+          const referenced = dialect.resolveRef<SchemaObject>(document, refPath)
+          if (referenced) {
+            resolvingRefs.add(refPath)
+            resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
+            resolvingRefs.delete(refPath)
+          }
+        } catch {
+          // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
         }
-      } catch {
-        // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
+        resolvedRefCache.set(refPath, resolvedSchema)
       }
+      resolvedSchema = resolvedRefCache.get(refPath) ?? null
     }
 
     return ast.createSchema({
@@ -133,7 +167,7 @@ function createSchemaParser(ctx: OasParserContext) {
       schema.additionalProperties === undefined
     ) {
       const [memberSchema] = schema.allOf as Array<SchemaObject | ReferenceObject>
-      const memberNode = parseSchema({ schema: memberSchema! as SchemaObject, name: null }, rawOptions)
+      const memberNode = parseSchema({ schema: memberSchema! as SchemaObject, name }, rawOptions)
       const { kind: _kind, ...memberNodeProps } = memberNode
       const mergedNullable = nullable || memberNode.nullable || undefined
       const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
@@ -150,6 +184,7 @@ function createSchemaParser(ctx: OasParserContext) {
         default: mergedDefault,
         example: schema.example ?? memberNode.example,
         pattern: schema.pattern ?? ('pattern' in memberNode ? memberNode.pattern : undefined),
+        format: schema.format ?? memberNode.format,
       } as ast.DistributiveOmit<ast.SchemaNode, 'kind'>)
     }
 
@@ -159,13 +194,13 @@ function createSchemaParser(ctx: OasParserContext) {
     }> = []
     const allOfMembers: Array<ast.SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
-        if (!isReference(item) || !name) return true
-        const deref = resolveRef<SchemaObject>(document, item.$ref)
-        if (!deref || !isDiscriminator(deref)) return true
+        if (!dialect.isReference(item) || !name) return true
+        const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
+        if (!deref || !dialect.isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
         const childRef = `${SCHEMA_REF_PREFIX}${name}`
-        const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
+        const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
           const discriminatorValue = ast.findDiscriminator(deref.discriminator.mapping, childRef)
@@ -179,7 +214,7 @@ function createSchemaParser(ctx: OasParserContext) {
         }
         return true
       })
-      .map((s) => parseSchema({ schema: s as SchemaObject }, rawOptions))
+      .map((s) => parseSchema({ schema: s as SchemaObject, name }, rawOptions))
 
     const syntheticStart = allOfMembers.length
 
@@ -189,9 +224,9 @@ function createSchemaParser(ctx: OasParserContext) {
 
       if (missingRequired.length) {
         const resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
-          if (!isReference(item)) return [item as SchemaObject]
-          const deref = resolveRef<SchemaObject>(document, item.$ref)
-          return deref && !isReference(deref) ? [deref] : []
+          if (!dialect.isReference(item)) return [item as SchemaObject]
+          const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
+          return deref && !dialect.isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
@@ -204,6 +239,7 @@ function createSchemaParser(ctx: OasParserContext) {
                       properties: { [key]: resolved.properties[key] },
                       required: [key],
                     } as SchemaObject,
+                    name,
                   },
                   rawOptions,
                 ),
@@ -217,6 +253,9 @@ function createSchemaParser(ctx: OasParserContext) {
 
     if (schema.properties) {
       const { allOf: _allOf, ...schemaWithoutAllOf } = schema
+      // Don't pass `name` here — the result must stay anonymous so it can be merged with the
+      // adjacent synthetic object in `mergeAdjacentObjectsLazy`. Nested enum qualification
+      // happens upstream via `convertObject`'s `setEnumName` propagation.
       allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions))
     }
 
@@ -226,7 +265,7 @@ function createSchemaParser(ctx: OasParserContext) {
 
     return ast.createSchema({
       type: 'intersection',
-      members: [...ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+      members: [...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
@@ -254,10 +293,10 @@ function createSchemaParser(ctx: OasParserContext) {
     const strategy: 'one' | 'any' = schema.oneOf ? 'one' : 'any'
     const unionBase = {
       ...buildSchemaNode(schema, name, nullable, defaultValue),
-      discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
+      discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
       strategy,
     }
-    const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+    const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : undefined
     const sharedPropertiesNode = schema.properties
       ? (() => {
           const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
@@ -270,9 +309,9 @@ function createSchemaParser(ctx: OasParserContext) {
 
     if (sharedPropertiesNode || discriminator?.mapping) {
       const members = unionMembers.map((s) => {
-        const ref = isReference(s) ? s.$ref : undefined
+        const ref = dialect.isReference(s) ? s.$ref : undefined
         const discriminatorValue = ast.findDiscriminator(discriminator?.mapping, ref)
-        const memberNode = parseSchema({ schema: s as SchemaObject }, rawOptions)
+        const memberNode = parseSchema({ schema: s as SchemaObject, name }, rawOptions)
 
         if (!discriminatorValue || !discriminator) {
           return memberNode
@@ -322,7 +361,7 @@ function createSchemaParser(ctx: OasParserContext) {
     return ast.createSchema({
       type: 'union',
       ...unionBase,
-      members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s as SchemaObject }, rawOptions))),
+      members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s as SchemaObject, name }, rawOptions))),
     })
   }
 
@@ -340,6 +379,7 @@ function createSchemaParser(ctx: OasParserContext) {
         title: schema.title,
         description: schema.description,
         deprecated: schema.deprecated,
+        format: schema.format,
       })
     }
 
@@ -454,6 +494,22 @@ function createSchemaParser(ctx: OasParserContext) {
 
     const nullInEnum = schema.enum!.includes(null)
     const filteredValues = (nullInEnum ? schema.enum!.filter((v) => v !== null) : schema.enum!) as Array<string | number | boolean>
+
+    // drf-spectacular `NullEnum` ({ enum: [null] }) is just `null`; an empty enum node would
+    // render as `never` (plugin-ts) / invalid `z.enum([])` (plugin-zod). Mirror the `const: null`
+    // branch so it renders as a clean `null` (not `z.null().nullable()`).
+    if (nullInEnum && filteredValues.length === 0) {
+      return ast.createSchema({
+        type: 'null',
+        primitive: 'null',
+        name,
+        title: schema.title,
+        description: schema.description,
+        deprecated: schema.deprecated,
+        format: schema.format,
+      })
+    }
+
     const enumNullable = nullable || nullInEnum || undefined
     const enumDefault = schema.default === null && enumNullable ? undefined : schema.default
     const enumPrimitive = getPrimitiveType(type)
@@ -470,6 +526,7 @@ function createSchemaParser(ctx: OasParserContext) {
       writeOnly: schema.writeOnly,
       default: enumDefault,
       example: schema.example,
+      format: schema.format,
     }
 
     const extensionKey = enumExtensionKeys.find((key) => key in schema)
@@ -513,19 +570,21 @@ function createSchemaParser(ctx: OasParserContext) {
       ? Object.entries(schema.properties).map(([propName, propSchema]) => {
           const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required
           const resolvedPropSchema = propSchema as SchemaObject
-          const propNullable = isNullable(resolvedPropSchema)
+          const propNullable = dialect.isNullable(resolvedPropSchema)
 
           const resolvedChildName = ast.childName(name, propName)
           const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
-          let schemaNode = ast.setEnumName(propNode, name, propName, options.enumSuffix)
-
-          const tupleNode = ast.narrowSchema(schemaNode, 'tuple')
-          if (tupleNode?.items) {
-            const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix))
-            if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
-              schemaNode = { ...tupleNode, items: namedItems }
+          const schemaNode = (() => {
+            const node = ast.setEnumName(propNode, name, propName, options.enumSuffix)
+            const tupleNode = ast.narrowSchema(node, 'tuple')
+            if (tupleNode?.items) {
+              const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix))
+              if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
+                return { ...tupleNode, items: namedItems }
+              }
             }
-          }
+            return node
+          })()
 
           return ast.createProperty({
             name: propName,
@@ -539,18 +598,15 @@ function createSchemaParser(ctx: OasParserContext) {
       : []
 
     const additionalProperties = schema.additionalProperties
-    let additionalPropertiesNode: ast.SchemaNode | boolean | undefined
-    if (additionalProperties === true) {
-      additionalPropertiesNode = true
-    } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
-      additionalPropertiesNode = parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
-    } else if (additionalProperties === false) {
-      additionalPropertiesNode = false
-    } else if (additionalProperties) {
-      additionalPropertiesNode = ast.createSchema({
-        type: typeOptionMap.get(options.unknownType)!,
-      })
-    }
+    const additionalPropertiesNode: ast.SchemaNode | boolean | undefined = (() => {
+      if (additionalProperties === true) return true
+      if (additionalProperties === false) return false
+      if (additionalProperties && Object.keys(additionalProperties).length > 0) {
+        return parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
+      }
+      if (additionalProperties) return ast.createSchema({ type: typeOptionMap.get(options.unknownType)! })
+      return undefined
+    })()
 
     const rawPatternProperties = 'patternProperties' in schema ? schema.patternProperties : undefined
 
@@ -578,7 +634,7 @@ function createSchemaParser(ctx: OasParserContext) {
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
 
-    if (isDiscriminator(schema) && schema.discriminator.mapping) {
+    if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
       const discPropName = schema.discriminator.propertyName
       const values = Object.keys(schema.discriminator.mapping)
       const enumName = name ? ast.enumPropName(name, discPropName, options.enumSuffix) : undefined
@@ -616,7 +672,7 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): ast.SchemaNode {
     const rawItems = schema.items as SchemaObject | undefined
-    const itemName = rawItems?.enum?.length && name ? ast.enumPropName(undefined, name, options.enumSuffix) : undefined
+    const itemName = rawItems?.enum?.length && name ? ast.enumPropName(null, name, options.enumSuffix) : name
     const items = rawItems ? [parseSchema({ schema: rawItems, name: itemName }, rawOptions)] : []
 
     return ast.createSchema({
@@ -683,15 +739,90 @@ function createSchemaParser(ctx: OasParserContext) {
       description: schema.description,
       deprecated: schema.deprecated,
       nullable,
+      format: schema.format,
+    })
+  }
+
+  /**
+   * Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
+   * into a `blob` node.
+   */
+  function convertBlob({ schema, name, nullable, defaultValue }: SchemaContext): ast.SchemaNode {
+    return ast.createSchema({
+      type: 'blob',
+      primitive: 'string',
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
+  /**
+   * Converts an OAS 3.1 multi-type array (e.g. `type: ['string', 'number']`) into a `UnionSchemaNode`.
+   *
+   * Returns `null` when only one non-`null` type remains (e.g. `['string', 'null']`), so `parseSchema`
+   * falls through and handles it as that single type with nullability already folded in.
+   */
+  function convertMultiType({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): ast.SchemaNode | null {
+    const types = schema.type as Array<string>
+    const nonNullTypes = types.filter((t) => t !== 'null')
+    if (nonNullTypes.length <= 1) return null
+
+    const arrayNullable = types.includes('null') || nullable || undefined
+    return ast.createSchema({
+      type: 'union',
+      members: nonNullTypes.map((t) => parseSchema({ schema: { ...schema, type: t } as SchemaObject, name }, rawOptions)),
+      ...buildSchemaNode(schema, name, arrayNullable, defaultValue),
+    })
+  }
+
+  /**
+   * Ordered schema-dispatch table. Order is significant: composition keywords (`$ref`, `allOf`,
+   * `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
+   * `type`. The first matching rule that produces a node wins; see {@link SchemaRule} for the
+   * match/convert/fall-through contract.
+   */
+  const schemaRules: Array<SchemaRule> = [
+    { name: 'ref', match: ({ schema }) => dialect.isReference(schema), convert: convertRef },
+    { name: 'allOf', match: ({ schema }) => !!schema.allOf?.length, convert: convertAllOf },
+    { name: 'union', match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length), convert: convertUnion },
+    { name: 'const', match: ({ schema }) => 'const' in schema && schema.const !== undefined, convert: convertConst },
+    { name: 'format', match: ({ schema }) => !!schema.format, convert: convertFormat },
+    {
+      name: 'blob',
+      match: ({ schema }) => dialect.isBinary(schema),
+      convert: convertBlob,
+    },
+    { name: 'multi-type', match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1, convert: convertMultiType },
+    {
+      name: 'constrained-string',
+      match: ({ schema, type }) => !type && (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined),
+      convert: convertString,
+    },
+    {
+      name: 'constrained-number',
+      match: ({ schema, type }) => !type && (schema.minimum !== undefined || schema.maximum !== undefined),
+      convert: (ctx) => convertNumeric(ctx, 'number'),
+    },
+    { name: 'enum', match: ({ schema }) => !!schema.enum?.length, convert: convertEnum },
+    {
+      name: 'object',
+      match: ({ schema, type }) => type === 'object' || !!schema.properties || !!schema.additionalProperties || 'patternProperties' in schema,
+      convert: convertObject,
+    },
+    { name: 'tuple', match: ({ schema }) => 'prefixItems' in schema, convert: convertTuple },
+    { name: 'array', match: ({ schema, type }) => type === 'array' || 'items' in schema, convert: convertArray },
+    { name: 'string', match: ({ type }) => type === 'string', convert: convertString },
+    { name: 'number', match: ({ type }) => type === 'number', convert: (ctx) => convertNumeric(ctx, 'number') },
+    { name: 'integer', match: ({ type }) => type === 'integer', convert: (ctx) => convertNumeric(ctx, 'integer') },
+    { name: 'boolean', match: ({ type }) => type === 'boolean', convert: convertBoolean },
+    { name: 'null', match: ({ type }) => type === 'null', convert: convertNull },
+  ]
+
   /**
    * Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
    *
-   * Dispatch order (first match wins): `$ref` → `allOf` → `oneOf`/`anyOf` → `const` → `format`
-   * → octet-stream blob → multi-type array → constraint-inferred type → `enum` → object/array/tuple/scalar
-   * → empty-schema fallback (`emptySchemaType` option).
+   * Builds the per-schema context, then runs it through the ordered {@link schemaRules} table
+   * via {@link ast.dispatch}. When no rule produces a node, falls back to the configured
+   * `emptySchemaType`.
    */
   function parseSchema({ schema, name }: { schema: SchemaObject; name?: string | null }, rawOptions?: Partial<ast.ParserOptions>): ast.SchemaNode {
     const options: ast.ParserOptions = {
@@ -703,11 +834,11 @@ function createSchemaParser(ctx: OasParserContext) {
       return parseSchema({ schema: flattenedSchema, name }, rawOptions)
     }
 
-    const nullable = isNullable(schema) || undefined
+    const nullable = dialect.isNullable(schema) || undefined
     const defaultValue = schema.default === null && nullable ? undefined : schema.default
     const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
 
-    const ctx: SchemaContext = {
+    const schemaCtx: SchemaContext = {
       schema,
       name,
       nullable,
@@ -717,58 +848,8 @@ function createSchemaParser(ctx: OasParserContext) {
       options,
     }
 
-    if (isReference(schema)) return convertRef(ctx)
-
-    if (schema.allOf?.length) return convertAllOf(ctx)
-    const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
-    if (unionMembers.length) return convertUnion(ctx)
-
-    if ('const' in schema && schema.const !== undefined) return convertConst(ctx)
-
-    if (schema.format) {
-      const formatResult = convertFormat(ctx)
-      if (formatResult) return formatResult
-    }
-
-    if (schema.type === 'string' && schema.contentMediaType === 'application/octet-stream') {
-      return ast.createSchema({
-        type: 'blob',
-        primitive: 'string',
-        ...buildSchemaNode(schema, name, nullable, defaultValue),
-      })
-    }
-
-    if (Array.isArray(schema.type) && schema.type.length > 1) {
-      const nonNullTypes = schema.type.filter((t) => t !== 'null') as string[]
-      const arrayNullable = schema.type.includes('null') || nullable || undefined
-
-      if (nonNullTypes.length > 1) {
-        return ast.createSchema({
-          type: 'union',
-          members: nonNullTypes.map((t) => parseSchema({ schema: { ...schema, type: t } as SchemaObject, name }, rawOptions)),
-          ...buildSchemaNode(schema, name, arrayNullable, defaultValue),
-        })
-      }
-    }
-
-    if (!type) {
-      if (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined) {
-        return convertString(ctx)
-      }
-      if (schema.minimum !== undefined || schema.maximum !== undefined) {
-        return convertNumeric(ctx, 'number')
-      }
-    }
-
-    if (schema.enum?.length) return convertEnum(ctx)
-    if (type === 'object' || schema.properties || schema.additionalProperties || 'patternProperties' in schema) return convertObject(ctx)
-    if ('prefixItems' in schema) return convertTuple(ctx)
-    if (type === 'array' || 'items' in schema) return convertArray(ctx)
-    if (type === 'string') return convertString(ctx)
-    if (type === 'number') return convertNumeric(ctx, 'number')
-    if (type === 'integer') return convertNumeric(ctx, 'integer')
-    if (type === 'boolean') return convertBoolean(ctx)
-    if (type === 'null') return convertNull(ctx)
+    const node = ast.dispatch(schemaRules, schemaCtx)
+    if (node) return node
 
     const emptyType = typeOptionMap.get(options.emptySchemaType)!
     return ast.createSchema({
@@ -776,21 +857,24 @@ function createSchemaParser(ctx: OasParserContext) {
       name,
       title: schema.title,
       description: schema.description,
+      format: schema.format,
     })
   }
 
   /**
    * Converts a dereferenced OAS parameter object into a `ParameterNode`.
    */
-  function parseParameter(options: ast.ParserOptions, param: Record<string, unknown>): ast.ParameterNode {
+  function parseParameter(options: ast.ParserOptions, param: Record<string, unknown>, parentName?: string): ast.ParameterNode {
     const required = (param['required'] as boolean | undefined) ?? false
+    const paramName = param['name'] as string
+    const schemaName = parentName && paramName ? pascalCase(`${parentName} ${paramName}`) : undefined
 
     const schema: ast.SchemaNode = param['schema']
-      ? parseSchema({ schema: param['schema'] as SchemaObject }, options)
+      ? parseSchema({ schema: param['schema'] as SchemaObject, name: schemaName }, options)
       : ast.createSchema({ type: typeOptionMap.get(options.unknownType)! })
 
     return ast.createParameter({
-      name: param['name'] as string,
+      name: paramName,
       in: param['in'] as ast.ParameterLocation,
       schema: {
         ...schema,
@@ -839,25 +923,27 @@ function createSchemaParser(ctx: OasParserContext) {
    * Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
    * `$ref` entries are skipped since their flags live on the dereferenced target.
    */
-  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): string[] | undefined {
-    if (!schema?.properties) return undefined
+  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): Array<string> | null {
+    if (!schema?.properties) return null
 
-    const keys: string[] = []
+    const keys: Array<string> = []
     for (const key in schema.properties) {
       const prop = schema.properties[key]
-      if (prop && !isReference(prop) && (prop as Record<string, unknown>)[flag]) {
+      if (prop && !dialect.isReference(prop) && (prop as Record<string, unknown>)[flag]) {
         keys.push(key)
       }
     }
-    return keys.length ? keys : undefined
+    return keys.length ? keys : null
   }
 
   /**
    * Converts an OAS `Operation` into an `OperationNode`.
    */
   function parseOperation(options: ast.ParserOptions, operation: Operation): ast.OperationNode {
+    const operationId = operation.getOperationId()
+    const operationName = operationId ? pascalCase(operationId) : undefined
     const parameters: Array<ast.ParameterNode> = getParameters(document, operation).map((param) =>
-      parseParameter(options, param as unknown as Record<string, unknown>),
+      parseParameter(options, param as unknown as Record<string, unknown>, operationName),
     )
 
     // Determine which content types to include in requestBody.content.
@@ -866,6 +952,7 @@ function createSchemaParser(ctx: OasParserContext) {
     const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(document, operation)
 
     const requestBodyMeta = getRequestBodyMeta(operation)
+    const requestBodyName = operationName ? `${operationName}Request` : undefined
 
     const content = allContentTypes.flatMap((ct) => {
       const schema = getRequestSchema(document, operation, { contentType: ct })
@@ -873,7 +960,7 @@ function createSchemaParser(ctx: OasParserContext) {
       return [
         {
           contentType: ct,
-          schema: ast.syncOptionality(parseSchema({ schema }, options), requestBodyMeta.required),
+          schema: ast.syncOptionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
           keysToOmit: collectPropertyKeysByFlag(schema, 'readOnly'),
         },
       ]
@@ -890,31 +977,45 @@ function createSchemaParser(ctx: OasParserContext) {
 
     const responses: Array<ast.ResponseNode> = operation.getResponseStatusCodes().map((statusCode) => {
       const responseObj = operation.getResponseByStatusCode(statusCode)
-      const responseSchema = getResponseSchema(document, operation, statusCode, { contentType: ctx.contentType })
 
-      const schema =
-        responseSchema && Object.keys(responseSchema).length > 0
-          ? parseSchema({ schema: responseSchema }, options)
-          : ast.createSchema({
-              type: typeOptionMap.get(options.emptySchemaType)!,
-            })
+      // Use `Status<code>` (matching plugin-ts's resolveResponseStatusName convention) so the
+      // qualified names for nested enums don't collide with top-level component schemas that
+      // happen to be named `<operation><statusCode>` (e.g. `GetMaintenance200`).
+      const responseName = operationName ? `${operationName}Status${statusCode}` : undefined
+      const { description } = getResponseMeta(responseObj)
+
+      const parseEntrySchema = (contentType?: string) => {
+        const raw = getResponseSchema(document, operation, statusCode, { contentType })
+        const node =
+          raw && Object.keys(raw).length > 0
+            ? parseSchema({ schema: raw, name: responseName }, options)
+            : ast.createSchema({ type: typeOptionMap.get(options.emptySchemaType)! })
+        return { schema: node, keysToOmit: collectPropertyKeysByFlag(raw, 'writeOnly') }
+      }
 
-      const { description, content } = getResponseMeta(responseObj)
-      const mediaType = content ? getMediaType(Object.keys(content)[0] ?? '') : getMediaType(operation.contentType ?? '')
+      // Build one entry per declared response content type so plugins can union the variants.
+      // When a global contentType is configured, restrict to that single type (mirrors requestBody).
+      const responseContentTypes = ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)
+      const content = responseContentTypes.map((contentType) => ({ contentType, ...parseEntrySchema(contentType) }))
+
+      // Body-less responses keep a single fallback entry so the response still resolves to a
+      // (void/any) schema, matching how `requestBody` only carries schemas inside `content`.
+      if (content.length === 0) {
+        content.push({ contentType: operation.contentType || 'application/json', ...parseEntrySchema(ctx.contentType) })
+      }
 
       return ast.createResponse({
         statusCode: statusCode as ast.StatusCode,
         description,
-        schema,
-        mediaType,
-        keysToOmit: collectPropertyKeysByFlag(responseSchema, 'writeOnly'),
+        content,
       })
     })
 
     const urlPath = new URLPath(operation.path)
 
     return ast.createOperation({
-      operationId: operation.getOperationId(),
+      operationId,
+      protocol: 'http',
       method: operation.method.toUpperCase() as ast.HttpMethod,
       path: urlPath.path,
       tags: operation.getTags().map((tag) => tag.name),
@@ -990,7 +1091,7 @@ export function parseOas(
   const baseOas = new BaseOas(document)
   const paths = baseOas.getPaths()
 
-  const operations: Array<ast.OperationNode> = Object.entries(paths).flatMap(([_path, methods]) =>
+  const operations: Array<ast.OperationNode> = Object.entries(paths).flatMap(([, methods]) =>
     Object.entries(methods)
       .map(([, operation]) => (operation ? _parseOperation(mergedOptions, operation) : null))
       .filter((op): op is ast.OperationNode => op !== null),