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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.2",
+  "version": "5.0.0-alpha.3",
   "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -46,8 +46,8 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.2",
-    "@kubb/core": "5.0.0-alpha.2"
+    "@kubb/ast": "5.0.0-alpha.3",
+    "@kubb/core": "5.0.0-alpha.3"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -6,6 +6,7 @@ import { resolveServerUrl } from './oas/resolveServerUrl.ts'
 import { parseFromConfig } from './oas/utils.ts'
 import { createOasParser } from './parser.ts'
 import type { OasAdapter } from './types.ts'
+import { getImports } from './utils.ts'
 
 export const adapterOasName = 'oas' satisfies OasAdapter['name']
 
@@ -42,6 +43,10 @@ export const adapterOas = defineAdapter<OasAdapter>((options) => {
     emptySchemaType = unknownType,
   } = options
 
+  // Mutable Map shared between `options` and each `parse()` call.
+  // Populated (and replaced) on every parse so consumers always see the latest state.
+  const nameMapping = new Map<string, string>()
+
   return {
     name: adapterOasName,
     options: {
@@ -56,6 +61,10 @@ export const adapterOas = defineAdapter<OasAdapter>((options) => {
       integerType,
       unknownType,
       emptySchemaType,
+      nameMapping,
+    },
+    getImports(node, resolve) {
+      return getImports({ node, nameMapping, resolve })
     },
     async parse(source) {
       const fakeConfig = sourceToFakeConfig(source)
@@ -75,6 +84,13 @@ export const adapterOas = defineAdapter<OasAdapter>((options) => {
       const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
 
       const parser = createOasParser(oas, { contentType, collisionDetection })
+
+      // Sync the adapter's shared nameMapping with the one computed by the parser.
+      nameMapping.clear()
+      for (const [key, value] of parser.nameMapping) {
+        nameMapping.set(key, value)
+      }
+
       const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType })
 
       return createRoot({

package/src/oas/types.ts

@@ -30,6 +30,25 @@ export type SchemaObject = OASSchemaObject & {
    */
   contentMediaType?: string
   $ref?: string
+  /**
+   * OAS 3.1 / JSON Schema: positional items in a tuple schema.
+   * Replaces the OAS 3.0 multi-item `items` array syntax.
+   */
+  prefixItems?: Array<SchemaObject | ReferenceObject>
+  /**
+   * JSON Schema: maps regex patterns to sub-schemas for additional property validation.
+   */
+  patternProperties?: Record<string, SchemaObject | boolean>
+  /**
+   * OAS 3.0 / JSON Schema: single-schema form.
+   * The OAS base type already includes this, but we re-declare it here to ensure
+   * the single-schema overload takes precedence over the multi-schema tuple form.
+   */
+  items?: SchemaObject | ReferenceObject
+  /**
+   * Enum values for this schema (narrowed from `unknown[]` in the base type).
+   */
+  enum?: Array<string | number | boolean | null>
 }
 
 /**

package/src/parser.ts

@@ -1,16 +1,5 @@
-import { pascalCase } from '@internals/utils'
-import {
-  collect,
-  createOperation,
-  createParameter,
-  createProperty,
-  createResponse,
-  createRoot,
-  createSchema,
-  narrowSchema,
-  schemaTypes,
-  transform,
-} from '@kubb/ast'
+import { pascalCase, URLPath } from '@internals/utils'
+import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
 import type {
   ArraySchemaNode,
   DateSchemaNode,
@@ -38,11 +27,11 @@ import type {
   TimeSchemaNode,
   UnionSchemaNode,
 } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
 import { enumExtensionKeys, formatMap, knownMediaTypes } from './constants.ts'
 import type { Oas } from './oas/Oas.ts'
-import type { contentType, Operation, SchemaObject } from './oas/types.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'
 
 /**
  * Distributive `Omit` — correctly distributes over union types so that
@@ -178,15 +167,6 @@ function formatToSchemaType(format: string): SchemaType | undefined {
   return formatMap[format as keyof typeof formatMap]
 }
 
-/**
- * Extracts the final path segment of a JSON Pointer `$ref` string.
- * For `#/components/schemas/Order` this returns `'Order'`.
- * Falls back to the full ref string when no slash is present.
- */
-function extractRefName($ref: string): string {
-  return $ref.split('/').at(-1) ?? $ref
-}
-
 /**
  * Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
  * Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
@@ -245,45 +225,15 @@ export type OasParser = {
    * 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
+
   /**
-   * Extracts `KubbFile.Import` entries from a `SchemaNode` tree by collecting
-   * all importable `ref` nodes. A `$ref` is considered importable when it resolves
-   * to a known component in the OAS spec (`oas.get($ref)` is truthy).
-   *
-   * The `resolve` callback is called with the schema name (last segment of the
-   * `$ref`, collision-corrected via the OAS name mapping) and must return the
-   * `{ name, path }` pair for the generated import, or `undefined` to skip it.
+   * Map from original `$ref` paths to their collision-resolved schema names.
+   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
    *
-   * @example
-   * ```ts
-   * const imports = parser.getImports(schemaNode, (schemaName) => ({
-   *   name: schemaManager.getName(schemaName, { type: 'type' }),
-   *   path: schemaManager.getFile(schemaName).path,
-   * }))
-   * ```
+   * Pass this to the standalone `getImports()` to resolve imports without holding
+   * a reference to the full parser or OAS instance.
    */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string } | undefined) => Array<KubbFile.Import>
-}
-
-/**
- * When a discriminator is present, replaces the discriminator property's schema with
- * an enum of the mapping keys so downstream code emits a precise literal-union type.
- * Returns the original schema unchanged when there is no discriminator or no mapping.
- */
-function applyDiscriminatorEnum(schema: SchemaObject): SchemaObject {
-  if (!isDiscriminator(schema)) return schema
-  const propName = schema.discriminator.propertyName
-  if (!schema.properties?.[propName]) return schema
-  return {
-    ...schema,
-    properties: {
-      ...schema.properties,
-      [propName]: {
-        ...(schema.properties[propName] as SchemaObject),
-        enum: schema.discriminator.mapping ? Object.keys(schema.discriminator.mapping) : undefined,
-      },
-    },
-  } as SchemaObject
+  nameMapping: Map<string, string>
 }
 
 /**
@@ -383,18 +333,17 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * reflected in generated JSDoc and type modifiers.
    */
   function convertRef({ schema, nullable, defaultValue }: SchemaContext): SchemaNode {
-    const schemaObject = schema as unknown as SchemaObject & { $ref: string }
     return createSchema({
       type: 'ref',
-      name: extractRefName(schemaObject.$ref),
-      ref: schemaObject.$ref,
+      name: extractRefName(schema.$ref!),
+      ref: schema.$ref,
       nullable,
-      description: schemaObject.description,
-      deprecated: schemaObject.deprecated,
-      readOnly: schemaObject.readOnly,
-      writeOnly: schemaObject.writeOnly,
-      pattern: schemaObject.type === 'string' ? schemaObject.pattern : undefined,
-      example: schemaObject.example,
+      description: schema.description,
+      deprecated: schema.deprecated,
+      readOnly: schema.readOnly,
+      writeOnly: schema.writeOnly,
+      pattern: schema.type === 'string' ? schema.pattern : undefined,
+      example: schema.example,
       default: defaultValue,
     })
   }
@@ -421,8 +370,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       !(Array.isArray(schema.required) && schema.required.length) &&
       schema.additionalProperties === undefined
     ) {
-      const [memberSchema] = schema.allOf as SchemaObject[]
-      const memberNode = convertSchema({ schema: memberSchema! }, options)
+      const [memberSchema] = schema.allOf as Array<SchemaObject | ReferenceObject>
+      const memberNode = convertSchema({ schema: memberSchema! as SchemaObject }, options)
       const { kind: _kind, ...memberNodeProps } = memberNode
       const mergedNullable = nullable || memberNode.nullable || undefined
       const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
@@ -444,22 +393,24 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
     // 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 allOfMembers: SchemaNode[] = (schema.allOf as SchemaObject[])
+    const allOfMembers: Array<SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
         if (!isReference(item) || !name) return true
-        const deref = oas.get<SchemaObject>((item as { $ref: string }).$ref)
+        const deref = oas.get<SchemaObject>(item.$ref)
         if (!deref || !isDiscriminator(deref)) return true
-        const parentUnion = (deref as SchemaObject).oneOf ?? (deref as SchemaObject).anyOf
+        const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
         const childRef = `#/components/schemas/${name}`
-        const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && (oneOfItem as { $ref: string }).$ref === childRef)
-        const inMapping = Object.values((deref as SchemaObject & { discriminator: { mapping?: Record<string, string> } }).discriminator.mapping ?? {}).some(
-          (v) => v === childRef,
-        )
+        const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
+        const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         return !inOneOf && !inMapping
       })
       .map((s) => convertSchema({ schema: s as SchemaObject }, options))
 
+    // 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) {
@@ -467,10 +418,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       const missingRequired = schema.required.filter((key) => !outerKeys.has(key))
 
       if (missingRequired.length) {
-        const resolvedMembers = (schema.allOf as SchemaObject[]).flatMap((item) => {
-          if (!isReference(item)) return [item]
+        const resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
+          if (!isReference(item)) return [item as SchemaObject]
           const deref = oas.get<SchemaObject>(item.$ref)
-          return deref && !isReference(deref) ? [deref as SchemaObject] : []
+          return deref && !isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
@@ -485,13 +436,14 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }
 
     if (schema.properties) {
-      const { allOf: _allOf, ...schemaWithoutAllOf } = schema as SchemaObject & { allOf?: unknown[] }
-      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf as SchemaObject }, options))
+      const { allOf: _allOf, ...schemaWithoutAllOf } = schema
+      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, options))
     }
 
+    // Merge consecutive anonymous object members within the synthetic portion — see `mergeAdjacentAnonymousObjects`.
     return createSchema({
       type: 'intersection',
-      members: allOfMembers,
+      members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
       ...buildSchemaBase(schema, name, nullable, defaultValue),
     })
   }
@@ -512,25 +464,39 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }
 
     if (schema.properties) {
-      const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema as SchemaObject & { oneOf?: unknown[]; anyOf?: unknown[] }
-      const propertiesNode = convertSchema({ schema: schemaWithoutUnion as SchemaObject }, options)
+      const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
+      const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+
+      // 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
 
       return createSchema({
         type: 'union',
         ...unionBase,
-        members: unionMembers.map((s) =>
-          createSchema({
+        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)
+
+          if (discriminatorValue && discriminator) {
+            propertiesNode = applyDiscriminatorEnum({ node: propertiesNode, propertyName: discriminator.propertyName, values: [discriminatorValue] })
+          }
+
+          return createSchema({
             type: 'intersection',
             members: [convertSchema({ schema: s as SchemaObject }, options), propertiesNode],
-          }),
-        ),
+          })
+        }),
       })
     }
 
     return createSchema({
       type: 'union',
       ...unionBase,
-      members: unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, options)),
+      members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, options))),
     })
   }
 
@@ -619,10 +585,9 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   function convertEnum({ schema, name, nullable, type, options }: SchemaContext): SchemaNode {
     // Malformed schema: `{ type: 'array', enum: [...] }` — normalize by moving the enum into items.
     if (type === 'array') {
-      const rawSchema = schema as unknown as { items?: SchemaObject; enum?: unknown[] }
-      const isItemsObject = typeof rawSchema.items === 'object' && !Array.isArray(rawSchema.items)
-      const normalizedItems = { ...(isItemsObject ? rawSchema.items : {}), enum: schema.enum } as SchemaObject
-      const { enum: _enum, ...schemaWithoutEnum } = schema as SchemaObject & { enum?: unknown[] }
+      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)
     }
 
@@ -716,21 +681,21 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * - not required + nullable → `nullish: true`
    */
   function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
-    // When a discriminator is present, override the discriminator property's schema to use
-    // an enum of the mapping keys for a precise literal-union type.
-    const resolvedSchema = applyDiscriminatorEnum(schema)
-
-    const properties: Array<PropertyNode> = resolvedSchema.properties
-      ? Object.entries(resolvedSchema.properties).map(([propName, propSchema]) => {
-          const required = Array.isArray(resolvedSchema.required) ? resolvedSchema.required.includes(propName) : !!resolvedSchema.required
+    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 derivedPropName = name ? pascalCase([name, propName, mergedOptions.enumSuffix].filter(Boolean).join(' ')) : undefined
+          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
 
           return createProperty({
             name: propName,
             schema: {
-              ...convertSchema({ schema: resolvedPropSchema, name: derivedPropName }, options),
+              ...schemaNode,
               nullable: propNullable || undefined,
               optional: !required && !propNullable ? true : undefined,
               nullish: !required && propNullable ? true : undefined,
@@ -740,7 +705,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         })
       : []
 
-    const additionalProperties = resolvedSchema.additionalProperties
+    const additionalProperties = schema.additionalProperties
     let additionalPropertiesNode: SchemaNode | true | undefined
     if (additionalProperties === true) {
       additionalPropertiesNode = true
@@ -752,21 +717,20 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       additionalPropertiesNode = createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
     }
 
-    const rawPatternProperties =
-      'patternProperties' in resolvedSchema ? (resolvedSchema as unknown as { patternProperties?: Record<string, SchemaObject> }).patternProperties : undefined
+    const rawPatternProperties = 'patternProperties' in schema ? schema.patternProperties : undefined
 
     const patternProperties = rawPatternProperties
       ? Object.fromEntries(
           Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [
             pattern,
-            (patternSchema as unknown) === true || Object.keys(patternSchema as object).length === 0
+            patternSchema === true || (typeof patternSchema === 'object' && Object.keys(patternSchema).length === 0)
               ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
               : convertSchema({ schema: patternSchema as SchemaObject }, options),
           ]),
         )
       : undefined
 
-    return createSchema({
+    const objectNode: SchemaNode = createSchema({
       type: 'object',
       primitive: 'object',
       properties,
@@ -774,6 +738,17 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       patternProperties,
       ...buildSchemaBase(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 })
+    }
+
+    return objectNode
   }
 
   /**
@@ -783,9 +758,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * after the prefix items is mapped to the rest parameter of the tuple.
    */
   function convertTuple({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
-    const rawSchema = schema as unknown as { prefixItems: SchemaObject[]; items?: SchemaObject }
-    const tupleItems = rawSchema.prefixItems.map((item) => convertSchema({ schema: item }, options))
-    const rest = rawSchema.items ? convertSchema({ schema: rawSchema.items }, options) : undefined
+    const tupleItems = (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item as SchemaObject }, options))
+    const rest = schema.items ? convertSchema({ schema: schema.items as SchemaObject }, options) : undefined
 
     return createSchema({
       type: 'tuple',
@@ -805,12 +779,11 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * `enumSuffix` is forwarded so generators can emit a named enum declaration.
    */
   function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
-    const rawSchema = schema as unknown as { items?: SchemaObject }
+    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 rawItems = rawSchema.items as SchemaObject | undefined
     const itemName = rawItems?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(' ')) : undefined
-    const items = rawSchema.items ? [convertSchema({ schema: rawSchema.items, name: itemName }, options)] : []
+    const items = rawItems ? [convertSchema({ schema: rawItems, name: itemName }, options)] : []
 
     return createSchema({
       type: 'array',
@@ -898,8 +871,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     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.
-    const flattenedSchema = flattenSchema(schema as unknown as Parameters<typeof flattenSchema>[0]) as SchemaObject | null
-    if (flattenedSchema && flattenedSchema !== (schema as unknown)) {
+    const flattenedSchema = flattenSchema(schema)
+    if (flattenedSchema && flattenedSchema !== schema) {
       return convertSchema({ schema: flattenedSchema, name }, options)
     }
 
@@ -933,7 +906,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }
 
     // OAS 3.1: `contentMediaType: 'application/octet-stream'` on a string schema signals binary data.
-    if (schema.type === 'string' && (schema as SchemaObject & { contentMediaType?: string }).contentMediaType === 'application/octet-stream') {
+    if (schema.type === 'string' && schema.contentMediaType === 'application/octet-stream') {
       return createSchema({ type: 'blob', primitive: 'string', ...buildSchemaBase(schema, name, nullable, defaultValue) })
     }
 
@@ -947,7 +920,7 @@ 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 }, options)),
+          members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject, name }, options)),
           ...buildSchemaBase(schema, name, arrayNullable, defaultValue),
         })
       }
@@ -984,16 +957,21 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
    */
   function parseParameter(options: Options, param: Record<string, unknown>): ParameterNode {
-    const schema =
-      param['schema'] && !isReference(param['schema'] as object)
+    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) })
 
     return createParameter({
       name: param['name'] as string,
       in: param['in'] as ParameterLocation,
-      schema,
-      required: (param['required'] as boolean | undefined) ?? false,
+      schema: {
+        ...schema,
+        optional: (!required || !!schema.optional) ? true : undefined,
+      },
+      required,
     })
   }
 
@@ -1037,7 +1015,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     return createOperation({
       operationId: operation.getOperationId(),
       method: operation.method.toUpperCase() as HttpMethod,
-      path: operation.path,
+      path: new URLPath(operation.path).URL,
       tags: operation.getTags().map((tag) => tag.name),
       summary: operation.getSummary() || undefined,
       description: operation.getDescription() || undefined,
@@ -1101,36 +1079,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     }) as SchemaNode
   }
 
-  /**
-   * Collects all `KubbFile.Import` descriptors needed by a `SchemaNode` tree.
-   *
-   * Walks the tree looking for `ref` nodes, verifies each `$ref` is resolvable in the spec,
-   * applies collision-resolved names from `nameMapping`, and calls `resolve` to obtain the
-   * import path and name. Returns an empty array for refs that cannot be resolved.
-   */
-  function getImports(node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string } | undefined): Array<KubbFile.Import> {
-    return collect<KubbFile.Import>(node, {
-      schema(schemaNode): KubbFile.Import | undefined {
-        if (schemaNode.type !== 'ref' || !schemaNode.ref) return
-        // Use the OAS instance to verify this $ref is importable (exists in the spec).
-        if (!oas.get(schemaNode.ref)) return
-
-        const rawName = extractRefName(schemaNode.ref)
-
-        // Apply collision-resolved name if available.
-        const schemaName = nameMapping.get(rawName) ?? rawName
-        const result = resolve(schemaName)
-        if (!result) return
-
-        return { name: [result.name], path: result.path }
-      },
-    })
-  }
-
   return {
-    parse: parse,
+    parse,
     convertSchema,
     resolveRefs,
-    getImports,
+    nameMapping,
   } as OasParser
 }

package/src/types.ts

@@ -82,6 +82,12 @@ export type OasAdapterResolvedOptions = {
   integerType: NonNullable<OasAdapterOptions['integerType']>
   unknownType: NonNullable<OasAdapterOptions['unknownType']>
   emptySchemaType: NonNullable<OasAdapterOptions['emptySchemaType']>
+  /**
+   * Map from original `$ref` paths to their collision-resolved schema names.
+   * Populated by the adapter after each `parse()` call.
+   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
+   */
+  nameMapping: Map<string, string>
 }
 
 export type OasAdapter = AdapterFactoryOptions<'oas', OasAdapterOptions, OasAdapterResolvedOptions>