@kubb/adapter-oas 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/parser.ts

@@ -1,189 +1,65 @@
-import { pascalCase, URLPath } from '@internals/utils'
-import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
+import { URLPath } from '@internals/utils'
+import {
+  childName,
+  createDiscriminantNode,
+  createOperation,
+  createParameter,
+  createProperty,
+  createResponse,
+  createRoot,
+  createSchema,
+  enumPropName,
+  extractRefName,
+  findDiscriminator,
+  mergeAdjacentObjects,
+  narrowSchema,
+  type ParserOptions,
+  setDiscriminatorEnum,
+  setEnumName,
+  simplifyUnion,
+  syncOptionality,
+} from '@kubb/ast'
 import type {
-  ArraySchemaNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
+  DistributiveOmit,
   HttpMethod,
-  IntersectionSchemaNode,
-  MediaType,
-  NumberSchemaNode,
-  ObjectSchemaNode,
   OperationNode,
   ParameterLocation,
   ParameterNode,
   PrimitiveSchemaType,
   PropertyNode,
-  RefSchemaNode,
   ResponseNode,
   RootNode,
-  ScalarSchemaNode,
   ScalarSchemaType,
   SchemaNode,
-  SchemaType,
   StatusCode,
-  StringSchemaNode,
-  TimeSchemaNode,
-  UnionSchemaNode,
 } from '@kubb/ast/types'
-import { enumExtensionKeys, formatMap, knownMediaTypes } from './constants.ts'
-import type { Oas } from './oas/Oas.ts'
-import type { contentType, Operation, ReferenceObject, SchemaObject } from './oas/types.ts'
-import { flattenSchema, isDiscriminator, isNullable, isReference } from './oas/utils.ts'
-import { applyDiscriminatorEnum, extractRefName, mergeAdjacentAnonymousObjects, simplifyUnionMembers } from './utils.ts'
+import BaseOas from 'oas'
+import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, typeOptionMap } from './constants.ts'
+import { isDiscriminator, isNullable, isReference } from './guards.ts'
+import { resolveRef } from './refs.ts'
+import {
+  buildSchemaNode,
+  flattenSchema,
+  getDateType,
+  getMediaType,
+  getParameters,
+  getPrimitiveType,
+  getRequestSchema,
+  getResponseSchema,
+  getSchemas,
+  getSchemaType,
+} from './resolvers.ts'
+import type { ContentType, Document, Operation, ReferenceObject, SchemaObject } from './types.ts'
 
 /**
- * Distributive `Omit` — correctly distributes over union types so that
- * `Omit<A | B, 'kind'>` produces `Omit<A, 'kind'> | Omit<B, 'kind'>`
- * rather than `Omit<A | B, 'kind'>`.
- */
-type DistributiveOmit<TValue, TKey extends PropertyKey> = TValue extends unknown ? Omit<TValue, TKey> : never
-
-/**
- * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
- */
-type DateTimeNodeByDateType = {
-  date: DateSchemaNode
-  string: DatetimeSchemaNode
-  stringOffset: DatetimeSchemaNode
-  stringLocal: DatetimeSchemaNode
-  false: StringSchemaNode
-}
-
-/**
- * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
- */
-type ResolveDateTimeNode<TDateType extends Options['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType ? TDateType : 'string']
-
-/**
- * Single source of truth: ordered list of `[shape, SchemaNode]` pairs.
- * `InferSchemaNode` walks this tuple in order and returns the node type of the first matching entry.
- * Parameterized over `TDateType` so `format: 'date-time'` resolves to the correct node based on the option.
- */
-type SchemaNodeMap<TDateType extends Options['dateType'] = Options['dateType']> = [
-  [{ $ref: string }, RefSchemaNode],
-  // allOf with sibling `properties` always produces an intersection (shared props are appended as a member).
-  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  // allOf with 2+ members always produces an intersection.
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
-  // Single-member allOf without sibling `properties` flattens to the member type.
-  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
-  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ const: null }, ScalarSchemaNode],
-  [{ const: string | number | boolean }, EnumSchemaNode],
-  // OAS 3.1 multi-type array: `{ type: ['string', 'integer'] }` → union node.
-  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
-  // `{ type: 'array', enum }` is normalized at runtime: enum moves into items → array node.
-  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
-  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
-  [{ type: 'object' }, ObjectSchemaNode],
-  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
-  [{ type: 'array' }, ArraySchemaNode],
-  [{ items: object }, ArraySchemaNode],
-  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
-  // Format entries with explicit type — placed before generic type entries so format wins.
-  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ type: string; format: 'date' }, DateSchemaNode],
-  [{ type: string; format: 'time' }, TimeSchemaNode],
-  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ format: 'date' }, DateSchemaNode],
-  [{ format: 'time' }, TimeSchemaNode],
-  [{ type: 'string' }, StringSchemaNode],
-  [{ type: 'number' }, NumberSchemaNode],
-  [{ type: 'integer' }, NumberSchemaNode],
-  [{ type: 'bigint' }, NumberSchemaNode],
-  [{ type: string }, ScalarSchemaNode],
-  // Inferred scalar types from constraints when no explicit type is present.
-  [{ minLength: number }, StringSchemaNode],
-  [{ maxLength: number }, StringSchemaNode],
-  [{ pattern: string }, StringSchemaNode],
-  [{ minimum: number }, NumberSchemaNode],
-  [{ maximum: number }, NumberSchemaNode],
-]
-
-export type InferSchemaNode<
-  TSchema extends SchemaObject,
-  TDateType extends Options['dateType'] = Options['dateType'],
-  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
-> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
-  ? TSchema extends TEntry[0]
-    ? TEntry[1]
-    : InferSchemaNode<TSchema, TDateType, TRest>
-  : SchemaNode
-
-/**
- * Controls how various OAS constructs are mapped to Kubb AST nodes.
- */
-export type Options = {
-  /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
-   */
-  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
-  /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
-   */
-  integerType?: 'number' | 'bigint'
-  /**
-   * AST type used when no schema type can be inferred.
-   */
-  unknownType: 'any' | 'unknown' | 'void'
-  /**
-   * AST type used for completely empty schemas (`{}`).
-   */
-  emptySchemaType: 'any' | 'unknown' | 'void'
-  /**
-   * Suffix appended to derived enum names when building property schema names.
-   */
-  enumSuffix: string
-}
-
-/**
- * Construction-time options for `createOasParser`.
- */
-export type OasParserOptions = {
-  contentType?: contentType
-  collisionDetection?: boolean
-}
-
-/**
- * Default values for all `Options` fields.
- */
-const DEFAULT_OPTIONS = {
-  dateType: 'string',
-  integerType: 'number',
-  unknownType: 'any',
-  emptySchemaType: 'any',
-  enumSuffix: 'enum',
-} as const satisfies Options
-
-/**
- * Looks up the Kubb `SchemaType` for a given OAS `format` string.
- * Returns `undefined` for formats not in `formatMap` (e.g. `int64`, `date-time`),
- * which are handled separately because their output depends on parser options.
- */
-function formatToSchemaType(format: string): SchemaType | undefined {
-  return formatMap[format as keyof typeof formatMap]
-}
-
-/**
- * Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
- * Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
- * `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
- */
-function getPrimitiveType(type: string | undefined): PrimitiveSchemaType {
-  if (type === 'number' || type === 'integer' || type === 'bigint') return type
-  if (type === 'boolean') return 'boolean'
-  return 'string'
-}
-
-/**
- * Narrows a raw content-type string to the `MediaType` union recognized by Kubb.
- * Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
+ * Construction-time context for the OAS parser.
+ *
+ * Holds the raw OpenAPI document and optional content-type override used when extracting
+ * request/response schemas.
  */
-function toMediaType(contentType: string): MediaType | undefined {
-  return knownMediaTypes.includes(contentType as MediaType) ? (contentType as MediaType) : undefined
+export type OasParserContext = {
+  document: Document
+  contentType?: ContentType
 }
 
 /**
@@ -192,178 +68,84 @@ function toMediaType(contentType: string): MediaType | undefined {
  */
 type SchemaContext = {
   schema: SchemaObject
-  name: string | undefined
+  name: string | null | undefined
   nullable: true | undefined
   defaultValue: unknown
   /**
    * Normalized single type string (first element when OAS 3.1 multi-type array).
    */
   type: string | undefined
-  options: Partial<Options> | undefined
-  mergedOptions: Options
+  rawOptions: Partial<ParserOptions> | undefined
+  options: ParserOptions
 }
 
 /**
- * The public interface returned by `createOasParser`.
+ * Normalize a malformed `{ type: 'array', enum: [...] }` schema by moving the
+ * enum values into the items sub-schema. This pattern is technically invalid OAS
+ * but appears in the wild and must be handled gracefully.
  */
-export type OasParser = {
-  /**
-   * Converts an OpenAPI/Swagger spec (wrapped in a Kubb `Oas` instance) into
-   * a `RootNode` — the top-level node of the `@kubb/ast` tree.
-   */
-  parse: <TOptions extends Partial<Options> = object>(options?: TOptions) => RootNode
-  convertSchema: <TFormat extends string, TSchema extends SchemaObject & { format?: TFormat }, TOptions extends Partial<Options> = object>(
-    params: { schema: TSchema; name?: string },
-    options?: TOptions,
-  ) => InferSchemaNode<TSchema, TOptions extends { dateType: Options['dateType'] } ? TOptions['dateType'] : (typeof DEFAULT_OPTIONS)['dateType']>
-  /**
-   * Walks `node` and replaces each `ref` value with the name returned by
-   * `resolveName`. The callback receives the full `$ref` path (e.g. `#/components/schemas/Order`)
-   * when available, falling back to the short name. Pass a no-op (`(n) => n`) to skip resolution.
-   *
-   * The optional `resolveEnumName` callback is called for inline `enum` nodes and should return
-   * the transformed name to use (e.g. with a plugin `transformers.name` applied).
-   */
-  resolveRefs: (node: SchemaNode, resolveName: (ref: string) => string | undefined, resolveEnumName?: (name: string) => string | undefined) => SchemaNode
+function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
+  const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
+  const normalizedItems: SchemaObject = { ...(isItemsObject ? (schema.items as SchemaObject) : {}), enum: schema.enum }
+  const { enum: _enum, ...schemaWithoutEnum } = schema
 
-  /**
-   * Map from original `$ref` paths to their collision-resolved schema names.
-   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
-   *
-   * Pass this to the standalone `getImports()` to resolve imports without holding
-   * a reference to the full parser or OAS instance.
-   */
-  nameMapping: Map<string, string>
+  return { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject
 }
 
 /**
- * Creates an OAS parser that converts an OpenAPI/Swagger spec into
- * the `@kubb/ast` tree.
- *
- * Options are passed per-call to `parse` or `convertSchema` rather than
- * at construction time, keeping the factory lightweight.
- *
- * This is the **kubb-parser** stage of the compilation lifecycle:
- *   OpenAPI / Swagger  →  Kubb AST
- *
- * No code is generated here; the resulting tree is spec-agnostic and can
- * be consumed by any downstream plugin (plugin-ts, plugin-zod, …).
+ * Builds the internal converter functions for a given `OasParserContext`.
  *
- * @example
- * ```ts
- * const parser = createOasParser(oas)
- * const root = parser.parse({ emptySchemaType: 'unknown' })
- * ```
+ * All `convert*` functions are defined as function declarations so they can freely
+ * reference each other and `parseSchema` via JS hoisting (mutual recursion).
  */
-export function createOasParser(oas: Oas, { contentType, collisionDetection }: OasParserOptions = {}): OasParser {
-  // Map from original component paths to resolved schema names (after collision resolution)
-  // e.g., { '#/components/schemas/Order': 'OrderSchema', '#/components/responses/Product': 'ProductResponse' }
-  const { schemas: schemaObjects, nameMapping } = oas.getSchemas({ contentType, collisionDetection })
+function createSchemaParser(ctx: OasParserContext) {
+  const document = ctx.document
+
+  // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
 
   /**
-   * Maps an `'any' | 'unknown' | 'void'` option string to the corresponding `SchemaType` constant.
-   * Used for both `unknownType` (unannotated schemas) and `emptySchemaType` (empty `{}` schemas).
+   * Tracks `$ref` paths that are currently being resolved to prevent infinite
+   * recursion when schemas contain circular references (e.g. `Pet → parent → Pet`).
    */
-  function resolveTypeOption(value: 'any' | 'unknown' | 'void'): ScalarSchemaType {
-    if (value === 'any') return schemaTypes.any
-    if (value === 'void') return schemaTypes.void
-    return schemaTypes.unknown
-  }
+  const resolvingRefs = new Set<string>()
 
   /**
-   * Resolves the AST type and datetime modifiers for a date/time format, honoring the `dateType` option.
-   * Returns `undefined` when `dateType` is `false`, meaning the format should fall through to `string`.
+   * Converts a `$ref` schema into a `RefSchemaNode`.
+   *
+   * The resolved schema is stored in `node.schema`. Usage-site sibling fields
+   * (description, readOnly, nullable, etc.) are stored directly on the ref node.
+   * Use `syncSchemaRef(node)` in printers to get a merged view of both.
+   * Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
    */
-  function getDateType(
-    options: Options,
-    format: 'date-time' | 'date' | 'time',
-  ): { type: 'datetime'; offset?: boolean; local?: boolean } | { type: 'date' | 'time'; representation: 'date' | 'string' } | undefined {
-    if (!options.dateType) {
-      return undefined
-    }
-
-    if (format === 'date-time') {
-      if (options.dateType === 'date') {
-        return { type: 'date', representation: 'date' }
-      }
-      if (options.dateType === 'stringOffset') {
-        return { type: 'datetime', offset: true }
-      }
-      if (options.dateType === 'stringLocal') {
-        return { type: 'datetime', local: true }
+  function convertRef({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
+    let resolvedSchema: SchemaNode | undefined
+    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)
+        }
+      } catch {
+        // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
       }
-      return { type: 'datetime', offset: false }
     }
 
-    if (format === 'date') {
-      return { type: 'date', representation: options.dateType === 'date' ? 'date' : 'string' }
-    }
-
-    // time
-    return { type: 'time', representation: options.dateType === 'date' ? 'date' : 'string' }
-  }
-
-  /**
-   * Shared metadata fields included in every `createSchema` call.
-   * Centralizes the common properties so sub-handlers don't repeat them.
-   */
-  function buildSchemaBase(schema: SchemaObject, name: string | undefined, nullable: true | undefined, defaultValue: unknown) {
-    return {
-      name,
-      nullable,
-      title: schema.title,
-      description: schema.description,
-      deprecated: schema.deprecated,
-      readOnly: schema.readOnly,
-      writeOnly: schema.writeOnly,
-      default: defaultValue,
-      example: schema.example,
-    } as const
-  }
-
-  // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
-  // They are defined as function declarations so they can reference each other
-  // and `convertSchema` freely (JS hoisting).
-
-  /**
-   * Converts a `$ref` schema pointer into a `RefSchemaNode`.
-   *
-   * In OAS 3.0 siblings of `$ref` are technically ignored by the spec, but Kubb intentionally
-   * preserves them so that annotations like `pattern`, `description`, and `nullable` are
-   * reflected in generated JSDoc and type modifiers.
-   */
-  function convertRef({ schema, nullable, defaultValue }: SchemaContext): SchemaNode {
     return createSchema({
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
       type: 'ref',
       name: extractRefName(schema.$ref!),
       ref: schema.$ref,
-      nullable,
-      description: schema.description,
-      deprecated: schema.deprecated,
-      readOnly: schema.readOnly,
-      writeOnly: schema.writeOnly,
-      pattern: schema.type === 'string' ? schema.pattern : undefined,
-      example: schema.example,
-      default: defaultValue,
+      schema: resolvedSchema,
     })
   }
 
   /**
-   * Converts a `allOf` schema into either a flattened member node (single-member `allOf`)
-   * or an `IntersectionSchemaNode` (multi-member `allOf`).
-   *
-   * Single-member `allOf` without sibling structural keys is the common OAS 3.0 pattern for
-   * annotating a `$ref` or primitive with extra constraints; it is flattened to avoid
-   * producing needless intersection wrappers.
-   *
-   * The flatten path is skipped when the outer schema carries structural keys that cannot be
-   * merged into annotation fields: `properties`, `required`, or `additionalProperties`.
-   * Those cases must become an intersection so the constraints are preserved.
-   *
-   * Circular references through discriminator parents are detected and skipped to prevent
-   * infinite recursion during code generation.
+   * Converts an `allOf` schema into a flattened node or an `IntersectionSchemaNode`.
    */
-  function convertAllOf({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
+  function convertAllOf({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
     if (
       schema.allOf!.length === 1 &&
       !schema.properties &&
@@ -371,7 +153,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       schema.additionalProperties === undefined
     ) {
       const [memberSchema] = schema.allOf as Array<SchemaObject | ReferenceObject>
-      const memberNode = convertSchema({ schema: memberSchema! as SchemaObject }, options)
+      const memberNode = parseSchema({ schema: memberSchema! as SchemaObject, name: null }, rawOptions)
       const { kind: _kind, ...memberNodeProps } = memberNode
       const mergedNullable = nullable || memberNode.nullable || undefined
       const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
@@ -391,28 +173,30 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       } as DistributiveOmit<SchemaNode, 'kind'>)
     }
 
-    // When a child schema extends a discriminator parent via allOf and the parent's oneOf/anyOf
-    // references that child back, skip that allOf item to prevent a circular type reference.
+    const filteredDiscriminantValues: Array<{ propertyName: string; value: string }> = []
     const allOfMembers: Array<SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
         if (!isReference(item) || !name) return true
-        const deref = oas.get<SchemaObject>(item.$ref)
+        const deref = resolveRef<SchemaObject>(document, item.$ref)
         if (!deref || !isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
         const childRef = `#/components/schemas/${name}`
         const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
-        return !inOneOf && !inMapping
+        if (inOneOf || inMapping) {
+          const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef)
+          if (discriminatorValue) {
+            filteredDiscriminantValues.push({ propertyName: deref.discriminator.propertyName, value: discriminatorValue })
+          }
+          return false
+        }
+        return true
       })
-      .map((s) => convertSchema({ schema: s as SchemaObject }, options))
+      .map((s) => parseSchema({ schema: s as SchemaObject }, rawOptions))
 
-    // Track where allOf-derived members end so only the synthetic members added below
-    // (injected required-key objects + outer-properties object) are candidates for merging.
     const syntheticStart = allOfMembers.length
 
-    // When `required` lists keys not present in the outer `properties`, resolve them from
-    // the allOf member schemas and inject them as extra intersection members.
     if (Array.isArray(schema.required) && schema.required.length) {
       const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : new Set<string>()
       const missingRequired = schema.required.filter((key) => !outerKeys.has(key))
@@ -420,14 +204,14 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       if (missingRequired.length) {
         const resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
           if (!isReference(item)) return [item as SchemaObject]
-          const deref = oas.get<SchemaObject>(item.$ref)
+          const deref = resolveRef<SchemaObject>(document, item.$ref)
           return deref && !isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
           for (const resolved of resolvedMembers) {
             if (resolved.properties?.[key]) {
-              allOfMembers.push(convertSchema({ schema: { properties: { [key]: resolved.properties[key] }, required: [key] } as SchemaObject }, options))
+              allOfMembers.push(parseSchema({ schema: { properties: { [key]: resolved.properties[key] }, required: [key] } as SchemaObject }, rawOptions))
               break
             }
           }
@@ -437,73 +221,108 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
     if (schema.properties) {
       const { allOf: _allOf, ...schemaWithoutAllOf } = schema
-      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, options))
+      allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions))
+    }
+
+    for (const { propertyName, value } of filteredDiscriminantValues) {
+      allOfMembers.push(createDiscriminantNode({ propertyName, value }))
     }
 
-    // Merge consecutive anonymous object members within the synthetic portion — see `mergeAdjacentAnonymousObjects`.
     return createSchema({
       type: 'intersection',
-      members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      members: [...mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
    * Converts a `oneOf` / `anyOf` schema into a `UnionSchemaNode`.
-   *
-   * Both keywords are treated identically — their members are concatenated into a single union.
-   * When sibling `properties` are present alongside `oneOf`/`anyOf`, each union member is
-   * individually intersected with the shared properties node to match the OAS pattern of
-   * adding common fields next to a discriminated union.
    */
-  function convertUnion({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
+  function convertUnion({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
+    function pickDiscriminatorPropertyNode(node: SchemaNode, propertyName: string): SchemaNode | null {
+      const objectNode = narrowSchema(node, 'object')
+      const discriminatorProperty = objectNode?.properties?.find((property) => property.name === propertyName)
+
+      if (!discriminatorProperty) {
+        return null
+      }
+
+      return createSchema({
+        type: 'object',
+        primitive: 'object',
+        properties: [discriminatorProperty],
+      })
+    }
+
     const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
     const unionBase = {
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
       discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
     }
+    const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+    const sharedPropertiesNode = schema.properties
+      ? (() => {
+          const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
+          const memberBaseSchema: SchemaObject = discriminator
+            ? (Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== 'discriminator')) as SchemaObject)
+            : schemaWithoutUnion
+          return parseSchema({ schema: memberBaseSchema, name }, rawOptions)
+        })()
+      : undefined
 
-    if (schema.properties) {
-      const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
-      const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+    if (sharedPropertiesNode || discriminator?.mapping) {
+      const members = unionMembers.map((s) => {
+        const ref = isReference(s) ? s.$ref : undefined
+        const discriminatorValue = findDiscriminator(discriminator?.mapping, ref)
+        const memberNode = parseSchema({ schema: s as SchemaObject }, rawOptions)
+
+        if (!discriminatorValue || !discriminator) {
+          return memberNode
+        }
 
-      // Strip discriminator so convertObject won't re-apply the full mapping enum.
-      const memberBaseSchema: SchemaObject = discriminator
-        ? (Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== 'discriminator')) as SchemaObject)
-        : schemaWithoutUnion
+        const narrowedDiscriminatorNode = sharedPropertiesNode
+          ? pickDiscriminatorPropertyNode(
+              setDiscriminatorEnum({
+                node: sharedPropertiesNode,
+                propertyName: discriminator.propertyName,
+                values: [discriminatorValue],
+              }),
+              discriminator.propertyName,
+            )
+          : undefined
 
-      return createSchema({
+        return createSchema({
+          type: 'intersection',
+          members: [memberNode, narrowedDiscriminatorNode ?? createDiscriminantNode({ propertyName: discriminator.propertyName, value: discriminatorValue })],
+        })
+      })
+
+      const unionNode = createSchema({
         type: 'union',
         ...unionBase,
-        members: unionMembers.map((s) => {
-          const ref = isReference(s) ? s.$ref : undefined
-          const discriminatorValue = discriminator?.mapping && ref ? Object.entries(discriminator.mapping).find(([, v]) => v === ref)?.[0] : undefined
-
-          let propertiesNode = convertSchema({ schema: memberBaseSchema, name }, options)
+        members,
+      })
 
-          if (discriminatorValue && discriminator) {
-            propertiesNode = applyDiscriminatorEnum({ node: propertiesNode, propertyName: discriminator.propertyName, values: [discriminatorValue] })
-          }
+      if (!sharedPropertiesNode) {
+        return unionNode
+      }
 
-          return createSchema({
-            type: 'intersection',
-            members: [convertSchema({ schema: s as SchemaObject }, options), propertiesNode],
-          })
-        }),
+      return createSchema({
+        type: 'intersection',
+        ...buildSchemaNode(schema, name, nullable, defaultValue),
+        members: [unionNode, sharedPropertiesNode],
       })
     }
 
     return createSchema({
       type: 'union',
       ...unionBase,
-      members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, options))),
+      members: simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s as SchemaObject }, rawOptions))),
     })
   }
 
   /**
-   * Converts an OAS 3.1 `const` schema into either a null scalar or a single-value `EnumSchemaNode`.
-   * `const: null` maps to a null scalar; any other value becomes a one-item enum so that generators
-   * can produce a precise literal type.
+   * Converts an OAS 3.1 `const` schema into a null scalar or a single-value `EnumSchemaNode`.
    */
   function convertConst({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
     const constValue = schema.const
@@ -516,7 +335,6 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         title: schema.title,
         description: schema.description,
         deprecated: schema.deprecated,
-        nullable,
       })
     }
 
@@ -525,22 +343,20 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       type: 'enum',
       primitive: constPrimitive,
       enumValues: [constValue as string | number | boolean],
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
-   * Handles `format`-based special types (date/time, uuid, email, blob, etc.).
-   * Returns `undefined` when the format should fall through to string handling
-   * (i.e. `format: 'date-time'` with `dateType: false`).
+   * Converts a format-annotated schema into a special-type `SchemaNode`.
+   * Returns `null` when the format should fall through to string handling (`dateType: false`).
    */
-  function convertFormat({ schema, name, nullable, defaultValue, mergedOptions }: SchemaContext): SchemaNode | undefined {
-    const base = buildSchemaBase(schema, name, nullable, defaultValue)
+  function convertFormat({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode | null {
+    const base = buildSchemaNode(schema, name, nullable, defaultValue)
 
-    // int64 is option-dependent so it can't live in the static formatMap.
     if (schema.format === 'int64') {
       return createSchema({
-        type: mergedOptions.integerType === 'bigint' ? 'bigint' : 'integer',
+        type: options.integerType === 'bigint' ? 'bigint' : 'integer',
         primitive: 'integer',
         ...base,
         min: schema.minimum,
@@ -550,10 +366,9 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       })
     }
 
-    // date-time / date / time are option-dependent and can't live in the static formatMap.
     if (schema.format === 'date-time' || schema.format === 'date' || schema.format === 'time') {
-      const dateType = getDateType(mergedOptions, schema.format)
-      if (!dateType) return undefined // dateType: false → fall through to string
+      const dateType = getDateType(options, schema.format)
+      if (!dateType) return null
 
       if (dateType.type === 'datetime') {
         return createSchema({ ...base, primitive: 'string' as const, type: 'datetime', offset: dateType.offset, local: dateType.local })
@@ -561,37 +376,38 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       return createSchema({ ...base, primitive: 'string' as const, type: dateType.type, representation: dateType.representation })
     }
 
-    const specialType = formatToSchemaType(schema.format!)
-    if (!specialType) return undefined
+    const specialType = getSchemaType(schema.format!)
+    if (!specialType) return null
 
     const specialPrimitive: PrimitiveSchemaType = specialType === 'number' || specialType === 'integer' || specialType === 'bigint' ? specialType : 'string'
 
     if (specialType === 'number' || specialType === 'integer' || specialType === 'bigint') {
       return createSchema({ ...base, primitive: specialPrimitive, type: specialType })
     }
+    if (specialType === 'url') {
+      return createSchema({ ...base, primitive: 'string' as const, type: 'url', min: schema.minLength, max: schema.maxLength })
+    }
+    if (specialType === 'ipv4') {
+      return createSchema({ ...base, primitive: 'string' as const, type: 'ipv4' })
+    }
+    if (specialType === 'ipv6') {
+      return createSchema({ ...base, primitive: 'string' as const, type: 'ipv6' })
+    }
+    if (specialType === 'uuid' || specialType === 'email') {
+      return createSchema({ ...base, primitive: 'string' as const, type: specialType, min: schema.minLength, max: schema.maxLength })
+    }
+
     return createSchema({ ...base, primitive: specialPrimitive, type: specialType as ScalarSchemaType })
   }
 
   /**
    * Converts an `enum` schema into an `EnumSchemaNode`.
-   *
-   * Handles several edge cases:
-   * - `{ type: 'array', enum }` (technically invalid OAS) — the enum is normalized into `items`.
-   * - `null` in enum values (OAS 3.0 nullable enum convention) — stripped and reflected as `nullable`.
-   * - `x-enumNames` / `x-enum-varnames` vendor extensions — produce named enum variants with explicit labels.
-   * - Numeric and boolean enums require a const-map representation because most generators cannot
-   *   use string-enum syntax for non-string values.
    */
-  function convertEnum({ schema, name, nullable, type, options }: SchemaContext): SchemaNode {
-    // Malformed schema: `{ type: 'array', enum: [...] }` — normalize by moving the enum into items.
+  function convertEnum({ schema, name, nullable, type, rawOptions }: SchemaContext): SchemaNode {
     if (type === 'array') {
-      const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
-      const normalizedItems: SchemaObject = { ...(isItemsObject ? (schema.items as SchemaObject) : {}), enum: schema.enum }
-      const { enum: _enum, ...schemaWithoutEnum } = schema
-      return convertSchema({ schema: { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject, name }, options)
+      return parseSchema({ schema: normalizeArrayEnum(schema), name }, rawOptions)
     }
 
-    // `null` in enum values is the OAS 3.0 convention for a nullable enum.
     const nullInEnum = schema.enum!.includes(null)
     const filteredValues = (nullInEnum ? schema.enum!.filter((v) => v !== null) : schema.enum!) as Array<string | number | boolean>
     const enumNullable = nullable || nullInEnum || undefined
@@ -612,56 +428,27 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       example: schema.example,
     }
 
-    // x-enumNames / x-enum-varnames: named variants with explicit labels take priority.
     const extensionKey = enumExtensionKeys.find((key) => key in schema)
-    if (extensionKey) {
-      const rawNames = (schema as Record<string, unknown>)[extensionKey] as Array<string | number>
-      const uniqueNames = [...new Set(rawNames)]
-      const enumType =
-        getPrimitiveType(type) === 'number' || getPrimitiveType(type) === 'integer'
-          ? ('number' as const)
-          : getPrimitiveType(type) === 'boolean'
-            ? ('boolean' as const)
-            : ('string' as const)
+    if (extensionKey || enumPrimitive === 'number' || enumPrimitive === 'integer' || enumPrimitive === 'boolean') {
+      const enumPrimitiveType = (enumPrimitive === 'number' || enumPrimitive === 'integer' ? 'number' : enumPrimitive === 'boolean' ? 'boolean' : 'string') as
+        | 'number'
+        | 'boolean'
+        | 'string'
+      const sourceValues = extensionKey
+        ? [...new Set((schema as Record<string, unknown>)[extensionKey] as Array<string | number>)]
+        : [...new Set(filteredValues)]
 
       return createSchema({
         ...enumBase,
-        enumType,
-        namedEnumValues: uniqueNames.map((label, index) => ({
+        primitive: enumPrimitiveType,
+        namedEnumValues: sourceValues.map((label, index) => ({
           name: String(label),
-          value: filteredValues[index] ?? label,
-          format: enumType,
-        })),
-      })
-    }
-
-    // Number / integer enum — must use a const map since most generators can't use string-enum for numbers.
-    if (type === 'number' || type === 'integer') {
-      return createSchema({
-        ...enumBase,
-        enumType: 'number' as const,
-        namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-          name: String(value),
-          value: value as number,
-          format: 'number' as const,
-        })),
-      })
-    }
-
-    // Boolean enum — same const-map approach as numeric.
-    if (type === 'boolean') {
-      return createSchema({
-        ...enumBase,
-        enumType: 'boolean' as const,
-        namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-          name: String(value),
-          value: value as boolean,
-          format: 'boolean' as const,
+          value: extensionKey ? (filteredValues[index] ?? label) : label,
+          primitive: enumPrimitiveType,
         })),
       })
     }
 
-    // Plain string enum (default path).
     return createSchema({
       ...enumBase,
       enumValues: [...new Set(filteredValues)],
@@ -669,36 +456,32 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   }
 
   /**
-   * Converts an object-like schema (`type: 'object'`, `properties`, `additionalProperties`,
-   * or `patternProperties`) into an `ObjectSchemaNode`.
-   *
-   * When a `discriminator` is present, the discriminator property's schema is replaced with an
-   * enum of the mapping keys so generators can produce a precise literal-union type for it.
-   *
-   * Property optionality follows OAS semantics:
-   * - required + not nullable → `required: true`
-   * - not required + not nullable → `optional: true`
-   * - not required + nullable → `nullish: true`
+   * Converts an object-like schema into an `ObjectSchemaNode`.
    */
-  function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
+  function convertObject({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): SchemaNode {
     const properties: Array<PropertyNode> = schema.properties
       ? 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 basePropName = name ? pascalCase([name, propName].join(' ')) : undefined
-          const propNode = convertSchema({ schema: resolvedPropSchema, name: basePropName }, options)
-          const isEnumNode = !!narrowSchema(propNode, 'enum')
-          const derivedPropName = isEnumNode && name ? pascalCase([name, propName, mergedOptions.enumSuffix].filter(Boolean).join(' ')) : basePropName
-          const schemaNode = isEnumNode && derivedPropName !== basePropName ? { ...propNode, name: derivedPropName } : propNode
+
+          const resolvedChildName = childName(name, propName)
+          const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
+          let schemaNode = setEnumName(propNode, name, propName, options.enumSuffix)
+
+          const tupleNode = narrowSchema(schemaNode, 'tuple')
+          if (tupleNode?.items) {
+            const namedItems = tupleNode.items.map((item) => setEnumName(item, name, propName, options.enumSuffix))
+            if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
+              schemaNode = { ...tupleNode, items: namedItems }
+            }
+          }
 
           return createProperty({
             name: propName,
             schema: {
               ...schemaNode,
-              nullable: propNullable || undefined,
-              optional: !required && !propNullable ? true : undefined,
-              nullish: !required && propNullable ? true : undefined,
+              nullable: schemaNode.type === 'null' ? undefined : propNullable || undefined,
             },
             required,
           })
@@ -706,15 +489,15 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       : []
 
     const additionalProperties = schema.additionalProperties
-    let additionalPropertiesNode: SchemaNode | true | undefined
+    let additionalPropertiesNode: SchemaNode | boolean | undefined
     if (additionalProperties === true) {
       additionalPropertiesNode = true
     } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
-      additionalPropertiesNode = convertSchema({ schema: additionalProperties as SchemaObject }, options)
+      additionalPropertiesNode = parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
     } else if (additionalProperties === false) {
-      additionalPropertiesNode = undefined
+      additionalPropertiesNode = false
     } else if (additionalProperties) {
-      additionalPropertiesNode = createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
+      additionalPropertiesNode = createSchema({ type: typeOptionMap.get(options.unknownType)! })
     }
 
     const rawPatternProperties = 'patternProperties' in schema ? schema.patternProperties : undefined
@@ -724,8 +507,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
           Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [
             pattern,
             patternSchema === true || (typeof patternSchema === 'object' && Object.keys(patternSchema).length === 0)
-              ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
-              : convertSchema({ schema: patternSchema as SchemaObject }, options),
+              ? createSchema({ type: typeOptionMap.get(options.unknownType)! })
+              : parseSchema({ schema: patternSchema as SchemaObject }, rawOptions),
           ]),
         )
       : undefined
@@ -736,16 +519,16 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       properties,
       additionalProperties: additionalPropertiesNode,
       patternProperties,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      minProperties: schema.minProperties,
+      maxProperties: schema.maxProperties,
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
 
-    // When a discriminator is present, replace the discriminator property's schema
-    // with an enum of the mapping keys for a precise literal-union type.
     if (isDiscriminator(schema) && schema.discriminator.mapping) {
       const discPropName = schema.discriminator.propertyName
       const values = Object.keys(schema.discriminator.mapping)
-      const enumName = name ? pascalCase([name, discPropName, mergedOptions.enumSuffix].filter(Boolean).join(' ')) : undefined
-      return applyDiscriminatorEnum({ node: objectNode, propertyName: discPropName, values, enumName })
+      const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : undefined
+      return setDiscriminatorEnum({ node: objectNode, propertyName: discPropName, values, enumName })
     }
 
     return objectNode
@@ -753,13 +536,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
   /**
    * Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
-   *
-   * Each `prefixItems` element maps to a positional tuple slot. An optional `items` schema
-   * after the prefix items is mapped to the rest parameter of the tuple.
    */
-  function convertTuple({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
-    const tupleItems = (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item as SchemaObject }, options))
-    const rest = schema.items ? convertSchema({ schema: schema.items as SchemaObject }, options) : undefined
+  function convertTuple({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
+    const tupleItems = (schema.prefixItems ?? []).map((item) => parseSchema({ schema: item as SchemaObject }, rawOptions))
+    const rest = schema.items ? parseSchema({ schema: schema.items as SchemaObject }, rawOptions) : createSchema({ type: 'any' })
 
     return createSchema({
       type: 'tuple',
@@ -768,22 +548,17 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       rest,
       min: schema.minItems,
       max: schema.maxItems,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
    * Converts a `type: 'array'` schema into an `ArraySchemaNode`.
-   *
-   * When the items schema is an inline enum, a name derived from the parent array's name and
-   * `enumSuffix` is forwarded so generators can emit a named enum declaration.
    */
-  function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
+  function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): SchemaNode {
     const rawItems = schema.items as SchemaObject | undefined
-    // When the array items schema contains an inline enum, derive a name from the parent
-    // array's name + enumSuffix so generators can emit a named enum declaration.
-    const itemName = rawItems?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(' ')) : undefined
-    const items = rawItems ? [convertSchema({ schema: rawItems, name: itemName }, options)] : []
+    const itemName = rawItems?.enum?.length && name ? enumPropName(undefined, name, options.enumSuffix) : undefined
+    const items = rawItems ? [parseSchema({ schema: rawItems, name: itemName }, rawOptions)] : []
 
     return createSchema({
       type: 'array',
@@ -792,12 +567,12 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       min: schema.minItems,
       max: schema.maxItems,
       unique: schema.uniqueItems ?? undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
-   * Converts a `type: 'string'` schema (without a special format) into a `StringSchemaNode`.
+   * Converts a `type: 'string'` schema into a `StringSchemaNode`.
    */
   function convertString({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
     return createSchema({
@@ -806,12 +581,12 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       min: schema.minLength,
       max: schema.maxLength,
       pattern: schema.pattern,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
-   * Converts a `type: 'number'` or `type: 'integer'` schema into the corresponding `SchemaNode`.
+   * Converts a `type: 'number'` or `type: 'integer'` schema.
    */
   function convertNumeric({ schema, name, nullable, defaultValue }: SchemaContext, type: 'number' | 'integer'): SchemaNode {
     return createSchema({
@@ -821,23 +596,24 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       max: schema.maximum,
       exclusiveMinimum: typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum : undefined,
       exclusiveMaximum: typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum : undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      multipleOf: schema.multipleOf,
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
-   * Converts a `type: 'boolean'` schema into a `BooleanSchemaNode`.
+   * Converts a `type: 'boolean'` schema.
    */
   function convertBoolean({ schema, name, nullable, defaultValue }: SchemaContext): SchemaNode {
     return createSchema({
       type: 'boolean',
       primitive: 'boolean',
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
 
   /**
-   * Converts an explicit `type: 'null'` or `const: null` schema into a `NullSchemaNode`.
+   * Converts an explicit `type: 'null'` schema.
    */
   function convertNull({ schema, name, nullable }: SchemaContext): SchemaNode {
     return createSchema({
@@ -852,67 +628,42 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   }
 
   /**
-   * Central dispatcher: converts an OAS `SchemaObject` into a `SchemaNode`.
+   * Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
    *
-   * Dispatch order (first match wins):
-   * 1. `$ref` pointer
-   * 2. `allOf` composition
-   * 3. `oneOf` / `anyOf` union
-   * 4. `const` literal (OAS 3.1)
-   * 5. `format`-based special type (date/time, uuid, blob, …)
-   * 6. OAS 3.1 `contentMediaType: 'application/octet-stream'` blob
-   * 7. OAS 3.1 multi-type array → union or fallthrough
-   * 8. Constraint-inferred type (minLength/maxLength → string; minimum/maximum → number)
-   * 9. `enum` values
-   * 10. Object / array / tuple / scalar by `type`
-   * 11. Empty schema fallback (`emptySchemaType` option)
+   * 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).
    */
-  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<Options>): SchemaNode {
-    const mergedOptions: Options = { ...DEFAULT_OPTIONS, ...options }
-    // Flatten keyword-only allOf fragments (no $ref, no structural keys) into the parent
-    // schema before parsing, so simple annotation patterns don't produce needless intersections.
+  function parseSchema({ schema, name }: { schema: SchemaObject; name?: string | null }, rawOptions?: Partial<ParserOptions>): SchemaNode {
+    const options: ParserOptions = { ...DEFAULT_PARSER_OPTIONS, ...rawOptions }
     const flattenedSchema = flattenSchema(schema)
     if (flattenedSchema && flattenedSchema !== schema) {
-      return convertSchema({ schema: flattenedSchema, name }, options)
+      return parseSchema({ schema: flattenedSchema, name }, rawOptions)
     }
 
     const nullable = isNullable(schema) || undefined
     const defaultValue = schema.default === null && nullable ? undefined : schema.default
-    // Normalize OAS 3.1 multi-type array to a single type string for the dispatch below.
     const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
 
-    const ctx: SchemaContext = { schema, name, nullable, defaultValue, type, options, mergedOptions }
+    const ctx: SchemaContext = { schema, name, nullable, defaultValue, type, rawOptions, options }
 
-    // $ref — pointer to another definition.
-    // In OAS 3.0 siblings of $ref are technically ignored, but Kubb intentionally preserves them
-    // so that annotations like `pattern`, `description`, and `nullable` are reflected in generated code.
     if (isReference(schema)) return convertRef(ctx)
 
-    // Composition keywords
     if (schema.allOf?.length) return convertAllOf(ctx)
     const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
     if (unionMembers.length) return convertUnion(ctx)
 
-    // OAS 3.1 const — a single fixed value, semantically equivalent to a one-item enum.
-    // `const: undefined` falls through to the empty-type fallback.
     if ('const' in schema && schema.const !== undefined) return convertConst(ctx)
 
-    // Format-based special types take precedence over `type`.
-    // `convertFormat` returns undefined when format should fall through to string (dateType: false).
-    // see https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
     if (schema.format) {
       const formatResult = convertFormat(ctx)
       if (formatResult) return formatResult
     }
 
-    // OAS 3.1: `contentMediaType: 'application/octet-stream'` on a string schema signals binary data.
     if (schema.type === 'string' && schema.contentMediaType === 'application/octet-stream') {
-      return createSchema({ type: 'blob', primitive: 'string', ...buildSchemaBase(schema, name, nullable, defaultValue) })
+      return createSchema({ type: 'blob', primitive: 'string', ...buildSchemaNode(schema, name, nullable, defaultValue) })
     }
 
-    // OAS 3.1: `type` may be an array — e.g. `["string", "integer", "null"]`.
-    // `null` in the array is the 3.1 equivalent of `nullable: true`; strip it and set the flag.
-    // When 2+ non-null types remain, produce a union; when exactly 1 non-null type remains, fall through.
     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
@@ -920,15 +671,12 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       if (nonNullTypes.length > 1) {
         return createSchema({
           type: 'union',
-          members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject, name }, options)),
-          ...buildSchemaBase(schema, name, arrayNullable, defaultValue),
+          members: nonNullTypes.map((t) => parseSchema({ schema: { ...schema, type: t } as SchemaObject, name }, rawOptions)),
+          ...buildSchemaNode(schema, name, arrayNullable, defaultValue),
         })
       }
     }
 
-    // Infer type from constraints when no explicit type is provided.
-    // minLength / maxLength / pattern → string; minimum / maximum → number.
-    // Note: minItems/maxItems do NOT infer array — arrays require an `items` key.
     if (!type) {
       if (schema.minLength !== undefined || schema.maxLength !== undefined || schema.pattern !== undefined) {
         return convertString(ctx)
@@ -948,52 +696,84 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     if (type === 'boolean') return convertBoolean(ctx)
     if (type === 'null') return convertNull(ctx)
 
-    const emptyType = resolveTypeOption(mergedOptions.emptySchemaType)
+    const emptyType = typeOptionMap.get(options.emptySchemaType)!
     return createSchema({ type: emptyType as ScalarSchemaType, name, title: schema.title, description: schema.description })
   }
 
   /**
-   * Converts a single dereferenced OAS parameter object into a `ParameterNode`.
-   * When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
+   * Converts a dereferenced OAS parameter object into a `ParameterNode`.
    */
-  function parseParameter(options: Options, param: Record<string, unknown>): ParameterNode {
+  function parseParameter(options: ParserOptions, param: Record<string, unknown>): ParameterNode {
     const required = (param['required'] as boolean | undefined) ?? false
 
-    const schema: SchemaNode =
-      param['schema'] && !isReference(param['schema'])
-        ? convertSchema({ schema: param['schema'] as SchemaObject }, options)
-        : createSchema({ type: resolveTypeOption(options.unknownType) })
+    const schema: SchemaNode = param['schema']
+      ? parseSchema({ schema: param['schema'] as SchemaObject }, options)
+      : createSchema({ type: typeOptionMap.get(options.unknownType)! })
 
     return createParameter({
       name: param['name'] as string,
       in: param['in'] as ParameterLocation,
       schema: {
         ...schema,
-        optional: (!required || !!schema.optional) ? true : undefined,
+        description: (param['description'] as string | undefined) ?? schema.description,
       },
       required,
     })
   }
 
   /**
-   * Converts an OAS `Operation` into an `OperationNode`, resolving parameters,
-   * request body, and all response codes into their AST node equivalents.
+   * Converts an OAS `Operation` into an `OperationNode`.
    */
-  function parseOperation(options: Options, oas: Oas, operation: Operation): OperationNode {
-    const parameters: Array<ParameterNode> = operation.getParameters().map((param) => {
-      const dereferenced = oas.dereferenceWithRef(param) as unknown as Record<string, unknown>
+  function parseOperation(options: ParserOptions, operation: Operation): OperationNode {
+    const parameters: Array<ParameterNode> = getParameters(document, operation).map((param) =>
+      parseParameter(options, param as unknown as Record<string, unknown>),
+    )
 
-      return parseParameter(options, dereferenced)
-    })
+    const requestBodySchema = getRequestSchema(document, operation, { contentType: ctx.contentType })
+    const requestBodySchemaNode = requestBodySchema ? parseSchema({ schema: requestBodySchema }, options) : undefined
+
+    const requestBodyDescription =
+      operation.schema.requestBody && !isReference(operation.schema.requestBody)
+        ? (operation.schema.requestBody as { description?: string }).description
+        : undefined
+
+    const requestBodyKeysToOmit = requestBodySchema?.properties
+      ? Object.entries(requestBodySchema.properties)
+          .filter(([, prop]) => !isReference(prop) && (prop as { readOnly?: boolean }).readOnly)
+          .map(([key]) => key)
+      : undefined
+
+    const requestBodyRequired =
+      operation.schema.requestBody && !isReference(operation.schema.requestBody)
+        ? (operation.schema.requestBody as { required?: boolean }).required === true
+        : false
 
-    const requestBodySchema = oas.getRequestSchema(operation)
-    const requestBody = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : undefined
+    const requestBodyContentType = (() => {
+      if (!operation.schema.requestBody || isReference(operation.schema.requestBody)) {
+        return undefined
+      }
+      const content = (operation.schema.requestBody as { content?: Record<string, unknown> }).content
+      return content ? Object.keys(content)[0] : undefined
+    })()
+
+    const requestBody = requestBodySchemaNode
+      ? {
+          description: requestBodyDescription,
+          schema: syncOptionality(requestBodySchemaNode, requestBodyRequired),
+          keysToOmit: requestBodyKeysToOmit?.length ? requestBodyKeysToOmit : undefined,
+          required: requestBodyRequired || undefined,
+          contentType: requestBodyContentType,
+        }
+      : undefined
 
     const responses: Array<ResponseNode> = operation.getResponseStatusCodes().map((statusCode) => {
       const responseObj = operation.getResponseByStatusCode(statusCode)
-      const responseSchema = oas.getResponseSchema(operation, statusCode)
+      const responseSchema = getResponseSchema(document, operation, statusCode, { contentType: ctx.contentType })
 
-      const schema = responseSchema && Object.keys(responseSchema).length > 0 ? convertSchema({ schema: responseSchema }, options) : undefined
+      const schema =
+        responseSchema && Object.keys(responseSchema).length > 0
+          ? parseSchema({ schema: responseSchema }, options)
+          : createSchema({ type: typeOptionMap.get(options.emptySchemaType)! })
 
       const description = typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj) ? responseObj.description : undefined
 
@@ -1002,20 +782,29 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
           ? (responseObj as { content?: Record<string, unknown> }).content
           : undefined
 
-      const mediaType = rawContent ? toMediaType(Object.keys(rawContent)[0] ?? '') : toMediaType(operation.contentType ?? '')
+      const mediaType = rawContent ? getMediaType(Object.keys(rawContent)[0] ?? '') : getMediaType(operation.contentType ?? '')
+
+      const keysToOmit = responseSchema?.properties
+        ? Object.entries(responseSchema.properties)
+            .filter(([, prop]) => !isReference(prop) && (prop as { writeOnly?: boolean }).writeOnly)
+            .map(([key]) => key)
+        : undefined
 
       return createResponse({
         statusCode: statusCode as StatusCode,
         description,
         schema,
         mediaType,
+        keysToOmit: keysToOmit?.length ? keysToOmit : undefined,
       })
     })
 
+    const urlPath = new URLPath(operation.path)
+
     return createOperation({
       operationId: operation.getOperationId(),
       method: operation.method.toUpperCase() as HttpMethod,
-      path: new URLPath(operation.path).URL,
+      path: urlPath.path,
       tags: operation.getTags().map((tag) => tag.name),
       summary: operation.getSummary() || undefined,
       description: operation.getDescription() || undefined,
@@ -1026,63 +815,57 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     })
   }
 
-  /**
-   * Converts an OpenAPI/Swagger spec (wrapped in a Kubb `Oas` instance) into
-   * a `RootNode` — the top-level node of the `@kubb/ast` tree.
-   */
-  function parse<TOptions extends Partial<Options> = object>(options?: TOptions): RootNode {
-    const mergedOptions: Options = { ...DEFAULT_OPTIONS, ...options }
+  return { parseSchema, parseOperation, parseParameter }
+}
 
-    const schemas: Array<SchemaNode> = Object.entries(schemaObjects).map(([name, schemaObject]) =>
-      convertSchema({ schema: schemaObject as SchemaObject, name }, mergedOptions),
-    )
+/**
+ * Converts a single `SchemaObject` into a `SchemaNode`.
+ *
+ * @example
+ * ```ts
+ * const ctx = { document }
+ * parseSchema(ctx, { schema: { type: 'string', format: 'uuid' } })
+ * ```
+ */
+export function parseSchema(ctx: OasParserContext, { schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<ParserOptions>): SchemaNode {
+  return createSchemaParser(ctx).parseSchema({ schema, name }, options)
+}
 
-    const paths = oas.getPaths()
+/**
+ * Converts the entire OpenAPI spec into a `RootNode` (the top-level `@kubb/ast` tree).
+ *
+ * This is the main entry point: `OpenAPI / Swagger → Kubb AST`.
+ * No code is generated here — the resulting tree is spec-agnostic and consumed by
+ * downstream plugins (`plugin-ts`, `plugin-zod`, …).
+ *
+ * @example
+ * ```ts
+ * const document = await parseFromConfig(config)
+ * const root = parseOas(document, { dateType: 'date', contentType: 'application/json' })
+ * ```
+ */
+export function parseOas(
+  document: Document,
+  options: Partial<ParserOptions> & { contentType?: ContentType } = {},
+): { root: RootNode; nameMapping: Map<string, string> } {
+  const { contentType, ...parserOptions } = options
+  const mergedOptions: ParserOptions = { ...DEFAULT_PARSER_OPTIONS, ...parserOptions }
 
-    const operations: Array<OperationNode> = Object.entries(paths).flatMap(([_path, methods]) =>
-      Object.entries(methods)
-        .map(([, operation]) => (operation ? parseOperation(mergedOptions, oas, operation) : null))
-        .filter((op): op is OperationNode => op !== null),
-    )
+  const { schemas: schemaObjects, nameMapping } = getSchemas(document, { contentType })
+  const { parseSchema: _parseSchema, parseOperation: _parseOperation } = createSchemaParser({ document, contentType })
 
-    return createRoot({ schemas, operations })
-  }
+  const schemas: Array<SchemaNode> = Object.entries(schemaObjects).map(([name, schema]) => _parseSchema({ schema, name }, mergedOptions))
 
-  /**
-   * Walks a `SchemaNode` tree and resolves all `ref` node names through the provided callbacks.
-   *
-   * `resolveName` handles all schema types; `resolveEnumName` (when provided) takes precedence
-   * for `enum` nodes, enabling a separate naming strategy for enums (e.g. different suffix).
-   *
-   * Collision-resolved names (from `nameMapping`) are applied before user-supplied resolvers.
-   */
-  function resolveRefs(node: SchemaNode, resolveName: (ref: string) => string | undefined, resolveEnumName?: (name: string) => string | undefined): SchemaNode {
-    return transform(node, {
-      schema(schemaNode) {
-        const schemaRef = narrowSchema(schemaNode, schemaTypes.ref)
-
-        if (schemaRef && (schemaRef.ref || schemaRef.name)) {
-          const rawRef = schemaRef.ref ?? schemaRef.name!
-          const resolved = resolveName(nameMapping.get(rawRef) ?? rawRef)
-          if (resolved) {
-            return { ...schemaNode, name: resolved }
-          }
-        }
+  const baseOas = new BaseOas(document)
+  const paths = baseOas.getPaths()
 
-        if (schemaNode.type === 'enum' && schemaNode.name) {
-          const resolved = (resolveEnumName ?? resolveName)(schemaNode.name)
-          if (resolved) {
-            return { ...schemaNode, name: resolved }
-          }
-        }
-      },
-    }) as SchemaNode
-  }
+  const operations: Array<OperationNode> = Object.entries(paths).flatMap(([_path, methods]) =>
+    Object.entries(methods)
+      .map(([, operation]) => (operation ? _parseOperation(mergedOptions, operation) : null))
+      .filter((op): op is OperationNode => op !== null),
+  )
+
+  const root = createRoot({ schemas, operations })
 
-  return {
-    parse,
-    convertSchema,
-    resolveRefs,
-    nameMapping,
-  } as OasParser
+  return { root, nameMapping }
 }