@kubb/adapter-oas 5.0.0-alpha.10 → 5.0.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.10",
+  "version": "5.0.0-alpha.12",
   "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "@kubb/fabric-core": "0.14.0",
-    "@redocly/openapi-core": "^2.24.0",
+    "@redocly/openapi-core": "^2.24.1",
     "@stoplight/yaml": "^4.3.0",
     "fflate": "^0.8.2",
     "jsonpointer": "^5.0.1",
@@ -46,8 +46,8 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.10",
-    "@kubb/core": "5.0.0-alpha.10"
+    "@kubb/ast": "5.0.0-alpha.12",
+    "@kubb/core": "5.0.0-alpha.12"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -2,6 +2,7 @@ import path from 'node:path'
 import { createRoot } from '@kubb/ast'
 import type { AdapterSource } from '@kubb/core'
 import { createAdapter } from '@kubb/core'
+import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
 import { resolveServerUrl } from './oas/resolveServerUrl.ts'
 import { parseFromConfig } from './oas/utils.ts'
 import { createOasParser } from './parser.ts'
@@ -36,11 +37,12 @@ export const adapterOas = createAdapter<OasAdapter>((options) => {
     serverIndex,
     serverVariables,
     discriminator = 'strict',
-    collisionDetection = false,
-    dateType = 'string',
-    integerType = 'number',
-    unknownType = 'any',
-    emptySchemaType = unknownType,
+    collisionDetection = true,
+    dateType = DEFAULT_PARSER_OPTIONS.dateType,
+    integerType = DEFAULT_PARSER_OPTIONS.integerType,
+    unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
+    enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix,
+    emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
   } = options
 
   // Mutable Map shared between `options` and each `parse()` call.
@@ -61,6 +63,7 @@ export const adapterOas = createAdapter<OasAdapter>((options) => {
       integerType,
       unknownType,
       emptySchemaType,
+      enumSuffix,
       nameMapping,
     },
     getImports(node, resolve) {
@@ -91,7 +94,7 @@ export const adapterOas = createAdapter<OasAdapter>((options) => {
         nameMapping.set(key, value)
       }
 
-      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType })
+      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType, enumSuffix })
 
       return createRoot({
         ...root,

package/src/constants.ts

@@ -1,7 +1,17 @@
 import type { SchemaType } from '@kubb/ast/types'
 import type { HttpMethods as OASHttpMethods } from 'oas/types'
+import type { ParserOptions } from './types.ts'
 
-// ─── Merge defaults ────────────────────────────────────────────────────────────
+/**
+ * Default values for all `Options` fields.
+ */
+export const DEFAULT_PARSER_OPTIONS = {
+  dateType: 'string',
+  integerType: 'number',
+  unknownType: 'any',
+  emptySchemaType: 'any',
+  enumSuffix: 'enum',
+} as const satisfies ParserOptions
 
 /**
  * OpenAPI version string written into merged document stubs.
@@ -18,8 +28,6 @@ export const MERGE_DEFAULT_TITLE = 'Merged API' as const
  */
 export const MERGE_DEFAULT_VERSION = '1.0.0' as const
 
-// ─── Schema analysis ───────────────────────────────────────────────────────────
-
 /**
  * JSON Schema keywords that indicate structural composition.
  * A schema fragment containing any of these keys must not be inlined into its
@@ -93,8 +101,6 @@ export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
  */
 export const SCALAR_PRIMITIVE_TYPES = new Set(['string', 'number', 'integer', 'bigint', 'boolean'] as const)
 
-// ─── HTTP ──────────────────────────────────────────────────────────────────────
-
 /**
  * Canonical HTTP method names for the Kubb OAS layer.
  * Keys are uppercase (used in generated code); values are the lowercase strings

package/src/parser.ts

@@ -1,4 +1,4 @@
-import { pascalCase, URLPath } from '@internals/utils'
+import { getUniqueName, pascalCase, URLPath } from '@internals/utils'
 import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
 import type {
   ArraySchemaNode,
@@ -27,10 +27,11 @@ import type {
   TimeSchemaNode,
   UnionSchemaNode,
 } from '@kubb/ast/types'
-import { enumExtensionKeys, formatMap, knownMediaTypes } from './constants.ts'
+import { DEFAULT_PARSER_OPTIONS, 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 type { ParserOptions } from './types.ts'
 import { applyDiscriminatorEnum, extractRefName, mergeAdjacentAnonymousObjects, simplifyUnionMembers } from './utils.ts'
 
 /**
@@ -54,14 +55,16 @@ type DateTimeNodeByDateType = {
 /**
  * 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']
+type ResolveDateTimeNode<TDateType extends ParserOptions['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']> = [
+type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
   [{ $ref: string }, RefSchemaNode],
   // allOf with sibling `properties` always produces an intersection (shared props are appended as a member).
   [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
@@ -105,7 +108,7 @@ type SchemaNodeMap<TDateType extends Options['dateType'] = Options['dateType']>
 
 export type InferSchemaNode<
   TSchema extends SchemaObject,
-  TDateType extends Options['dateType'] = Options['dateType'],
+  TDateType extends ParserOptions['dateType'] = 'string',
   TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
 > = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
   ? TSchema extends TEntry[0]
@@ -113,32 +116,6 @@ export type InferSchemaNode<
     : 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`.
  */
@@ -147,17 +124,6 @@ export type OasParserOptions = {
   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`),
@@ -199,8 +165,8 @@ type SchemaContext = {
    * Normalized single type string (first element when OAS 3.1 multi-type array).
    */
   type: string | undefined
-  options: Partial<Options> | undefined
-  mergedOptions: Options
+  options: Partial<ParserOptions> | undefined
+  mergedOptions: ParserOptions
 }
 
 /**
@@ -211,11 +177,11 @@ 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>(
+  parse: <TOptions extends Partial<ParserOptions> = object>(options?: TOptions) => RootNode
+  convertSchema: <TFormat extends string, TSchema extends SchemaObject & { format?: TFormat }, TOptions extends Partial<ParserOptions> = object>(
     params: { schema: TSchema; name?: string },
     options?: TOptions,
-  ) => InferSchemaNode<TSchema, TOptions extends { dateType: Options['dateType'] } ? TOptions['dateType'] : (typeof DEFAULT_OPTIONS)['dateType']>
+  ) => InferSchemaNode<TSchema, TOptions extends { dateType: ParserOptions['dateType'] } ? TOptions['dateType'] : 'string'>
   /**
    * 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`)
@@ -260,6 +226,14 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   // e.g., { '#/components/schemas/Order': 'OrderSchema', '#/components/responses/Product': 'ProductResponse' }
   const { schemas: schemaObjects, nameMapping } = oas.getSchemas({ contentType, collisionDetection })
 
+  // Legacy enum name deduplication: tracks used enum names and appends numeric suffixes
+  // (e.g. ParamsStatusEnum, ParamsStatusEnum2) when collisionDetection is disabled.
+  const usedEnumNames: Record<string, number> = {}
+
+  // Only apply legacy naming when collisionDetection is explicitly false.
+  // When undefined (e.g. direct parser usage without adapter), use the default (new) behavior.
+  const isLegacyNaming = collisionDetection === false
+
   /**
    * Maps an `'any' | 'unknown' | 'void'` option string to the corresponding `SchemaType` constant.
    * Used for both `unknownType` (unannotated schemas) and `emptySchemaType` (empty `{}` schemas).
@@ -275,7 +249,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * Returns `undefined` when `dateType` is `false`, meaning the format should fall through to `string`.
    */
   function getDateType(
-    options: Options,
+    options: ParserOptions,
     format: 'date-time' | 'date' | 'time',
   ): { type: 'datetime'; offset?: boolean; local?: boolean } | { type: 'date' | 'time'; representation: 'date' | 'string' } | undefined {
     if (!options.dateType) {
@@ -307,7 +281,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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) {
+  function renderSchemaBase(schema: SchemaObject, name: string | undefined, nullable: true | undefined, defaultValue: unknown) {
     return {
       name,
       nullable,
@@ -444,7 +418,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     return createSchema({
       type: 'intersection',
       members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -459,7 +433,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   function convertUnion({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
     const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
     const unionBase = {
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
       discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
     }
 
@@ -472,6 +446,10 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         ? (Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== 'discriminator')) as SchemaObject)
         : schemaWithoutUnion
 
+      // Convert shared properties once to avoid duplicate enum naming
+      // (e.g. StatusEnum appearing twice and getting a numeric suffix).
+      const sharedPropertiesNode = convertSchema({ schema: memberBaseSchema, name: isLegacyNaming ? undefined : name }, options)
+
       return createSchema({
         type: 'union',
         ...unionBase,
@@ -479,7 +457,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
           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)
+          let propertiesNode = sharedPropertiesNode
 
           if (discriminatorValue && discriminator) {
             propertiesNode = applyDiscriminatorEnum({ node: propertiesNode, propertyName: discriminator.propertyName, values: [discriminatorValue] })
@@ -525,7 +503,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       type: 'enum',
       primitive: constPrimitive,
       enumValues: [constValue as string | number | boolean],
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -535,7 +513,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * (i.e. `format: 'date-time'` with `dateType: false`).
    */
   function convertFormat({ schema, name, nullable, defaultValue, mergedOptions }: SchemaContext): SchemaNode | undefined {
-    const base = buildSchemaBase(schema, name, nullable, defaultValue)
+    const base = renderSchemaBase(schema, name, nullable, defaultValue)
 
     // int64 is option-dependent so it can't live in the static formatMap.
     if (schema.format === 'int64') {
@@ -684,17 +662,64 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * - not required + not nullable → `optional: true`
    * - not required + nullable → `nullish: true`
    */
+  /**
+   * Builds the propagation name for a child property during recursive schema conversion.
+   *
+   * - **Legacy naming** (`isLegacyNaming`): only the immediate property key is used
+   *   (e.g. `Params` for property `params`), keeping nested names short.
+   * - **Default naming**: the parent name is prepended so the full path is encoded
+   *   (e.g. `OrderParams` when parent is `Order`).
+   */
+  function resolveChildName(parentName: string | undefined, propName: string): string | undefined {
+    if (isLegacyNaming) {
+      return pascalCase(propName)
+    }
+    return parentName ? pascalCase([parentName, propName].join(' ')) : undefined
+  }
+
+  /**
+   * Derives the final name for an enum property schema node.
+   *
+   * The raw name always includes the enum suffix (e.g. `StatusEnum`).
+   * In legacy mode an additional deduplication step appends a numeric suffix
+   * when the same name has already been used (e.g. `ParamsStatusEnum2`).
+   */
+  function resolveEnumPropName(parentName: string | undefined, propName: string, enumSuffix: string): string {
+    const raw = pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
+    return isLegacyNaming ? getUniqueName(raw, usedEnumNames) : raw
+  }
+
+  /**
+   * Given a freshly-converted property schema, returns the node with a correct
+   * `name` attached — or stripped — depending on whether the node is a named
+   * enum, a boolean const-enum (always inlined), or a regular schema.
+   */
+  function applyEnumName(propNode: SchemaNode, parentName: string | undefined, propName: string, enumSuffix: string): SchemaNode {
+    const enumNode = narrowSchema(propNode, 'enum')
+
+    // Boolean-primitive enum nodes (e.g. `const: false`) are always inlined as
+    // literal types and must not receive a named identifier.
+    if (enumNode?.primitive === 'boolean') {
+      return { ...propNode, name: undefined }
+    }
+
+    if (enumNode) {
+      return { ...propNode, name: resolveEnumPropName(parentName, propName, enumSuffix) }
+    }
+
+    return propNode
+  }
+
   function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }: 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 childName = resolveChildName(name, propName)
+          const propNode = convertSchema({ schema: resolvedPropSchema, name: childName }, options)
+          const schemaNode = applyEnumName(propNode, name, propName, mergedOptions.enumSuffix)
 
           return createProperty({
             name: propName,
@@ -740,7 +765,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       properties,
       additionalProperties: additionalPropertiesNode,
       patternProperties,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
 
     // When a discriminator is present, replace the discriminator property's schema
@@ -748,7 +773,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     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
+      const enumName = name ? resolveEnumPropName(name, discPropName, mergedOptions.enumSuffix) : undefined
       return applyDiscriminatorEnum({ node: objectNode, propertyName: discPropName, values, enumName })
     }
 
@@ -772,7 +797,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       rest,
       min: schema.minItems,
       max: schema.maxItems,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -784,9 +809,9 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    */
   function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }: 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
+    // When the items schema contains an inline enum, derive a named identifier
+    // so generators can emit a standalone enum declaration.
+    const itemName = rawItems?.enum?.length && name ? resolveEnumPropName(undefined, name, mergedOptions.enumSuffix) : undefined
     const items = rawItems ? [convertSchema({ schema: rawItems, name: itemName }, options)] : []
 
     return createSchema({
@@ -796,7 +821,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       min: schema.minItems,
       max: schema.maxItems,
       unique: schema.uniqueItems ?? undefined,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -810,7 +835,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       min: schema.minLength,
       max: schema.maxLength,
       pattern: schema.pattern,
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -825,7 +850,7 @@ 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),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -836,7 +861,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     return createSchema({
       type: 'boolean',
       primitive: 'boolean',
-      ...buildSchemaBase(schema, name, nullable, defaultValue),
+      ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
 
@@ -871,8 +896,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 10. Object / array / tuple / scalar by `type`
    * 11. Empty schema fallback (`emptySchemaType` option)
    */
-  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<Options>): SchemaNode {
-    const mergedOptions: Options = { ...DEFAULT_OPTIONS, ...options }
+  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<ParserOptions>): SchemaNode {
+    const mergedOptions: ParserOptions = { ...DEFAULT_PARSER_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)
@@ -911,7 +936,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.contentMediaType === 'application/octet-stream') {
-      return createSchema({ type: 'blob', primitive: 'string', ...buildSchemaBase(schema, name, nullable, defaultValue) })
+      return createSchema({ type: 'blob', primitive: 'string', ...renderSchemaBase(schema, name, nullable, defaultValue) })
     }
 
     // OAS 3.1: `type` may be an array — e.g. `["string", "integer", "null"]`.
@@ -925,7 +950,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         return createSchema({
           type: 'union',
           members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject, name }, options)),
-          ...buildSchemaBase(schema, name, arrayNullable, defaultValue),
+          ...renderSchemaBase(schema, name, arrayNullable, defaultValue),
         })
       }
     }
@@ -960,7 +985,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * 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`.
    */
-  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 =
@@ -984,11 +1009,24 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
    * Converts an OAS `Operation` into an `OperationNode`, resolving parameters,
    * request body, and all response codes into their AST node equivalents.
    */
-  function parseOperation(options: Options, oas: Oas, operation: Operation): OperationNode {
+  function parseOperation(options: ParserOptions, oas: Oas, operation: Operation): OperationNode {
     const parameters: Array<ParameterNode> = oas.getParameters(operation).map((param) => parseParameter(options, param as unknown as Record<string, unknown>))
 
     const requestBodySchema = oas.getRequestSchema(operation)
-    const requestBody = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : undefined
+    const requestBodySchemaNode = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : undefined
+
+    const requestBodyKeysToOmit = requestBodySchema?.properties
+      ? Object.entries(requestBodySchema.properties)
+          .filter(([, prop]) => !isReference(prop) && (prop as { readOnly?: boolean }).readOnly)
+          .map(([key]) => key)
+      : undefined
+
+    const requestBody = requestBodySchemaNode
+      ? {
+          schema: requestBodySchemaNode,
+          keysToOmit: requestBodyKeysToOmit?.length ? requestBodyKeysToOmit : undefined,
+        }
+      : undefined
 
     const responses: Array<ResponseNode> = operation.getResponseStatusCodes().map((statusCode) => {
       const responseObj = operation.getResponseByStatusCode(statusCode)
@@ -1008,11 +1046,18 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
       const mediaType = rawContent ? toMediaType(Object.keys(rawContent)[0] ?? '') : toMediaType(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,
       })
     })
 
@@ -1034,8 +1079,8 @@ 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 }
+  function parse<TOptions extends Partial<ParserOptions> = object>(options?: TOptions): RootNode {
+    const mergedOptions: ParserOptions = { ...DEFAULT_PARSER_OPTIONS, ...options }
 
     const schemas: Array<SchemaNode> = Object.entries(schemaObjects).map(([name, schemaObject]) =>
       convertSchema({ schema: schemaObject as SchemaObject, name }, mergedOptions),

package/src/types.ts

@@ -2,6 +2,32 @@ import type { AdapterFactoryOptions } from '@kubb/core'
 import type { Oas as OasClass } from './oas/Oas.ts'
 import type { contentType } from './oas/types.ts'
 
+/**
+ * Controls how various OAS constructs are mapped to Kubb AST nodes.
+ */
+export type ParserOptions = {
+  /**
+   * 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: 'enum' | (string & {})
+}
+
 export type OasAdapterOptions = {
   /**
    * Validate the OpenAPI spec before parsing.
@@ -41,8 +67,13 @@ export type OasAdapterOptions = {
    */
   discriminator?: 'strict' | 'inherit'
   /**
-   * Automatically resolve name collisions across schema components.
-   * @default false
+   * Enable collision detection for inline enum and schema type names.
+   * When `true` (default), full-path names are used and name collisions
+   * across schema components are automatically resolved (e.g. `OrderParamsStatusEnum`).
+   * When `false`, enum names use only the immediate property context
+   * (e.g. `ParamsStatusEnum`) matching the v4 naming conventions, with numeric
+   * suffixes for deduplication (e.g. `ParamsStatusEnum2`).
+   * @default true
    */
   collisionDetection?: boolean
   /**
@@ -52,23 +83,7 @@ export type OasAdapterOptions = {
    * - `false` falls through to a plain `string` node.
    * @default 'string'
    */
-  dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
-  /**
-   * Whether `type: 'integer'` / `format: 'int64'` produces `number` or `bigint` nodes.
-   * @default 'number'
-   */
-  integerType?: 'number' | 'bigint'
-  /**
-   * AST type used when no schema type can be inferred.
-   * @default 'any'
-   */
-  unknownType?: 'any' | 'unknown' | 'void'
-  /**
-   * AST type used for completely empty schemas (`{}`).
-   * @default `unknownType`
-   */
-  emptySchemaType?: 'any' | 'unknown' | 'void'
-}
+} & Partial<ParserOptions>
 
 export type OasAdapterResolvedOptions = {
   validate: boolean
@@ -82,6 +97,7 @@ export type OasAdapterResolvedOptions = {
   integerType: NonNullable<OasAdapterOptions['integerType']>
   unknownType: NonNullable<OasAdapterOptions['unknownType']>
   emptySchemaType: NonNullable<OasAdapterOptions['emptySchemaType']>
+  enumSuffix: OasAdapterOptions['enumSuffix']
   /**
    * Map from original `$ref` paths to their collision-resolved schema names.
    * Populated by the adapter after each `parse()` call.