feat: add parser.transforms.schemas.name configuration and implementation

Co-authored-by: mrlubos <[e-mail]>

packages/shared/src/config/parser/config.ts

···
             name: '{{name}}',
           },
         },
+        schemas: {
+          enabled: false,
+          name: '{{name}}',
+        },
       },
       validate_EXPERIMENTAL: false,
     },
···
                   }),
                 },
                 value: fields.readWrite,
+              }),
+              schemas: valueToObject({
+                defaultValue: {
+                  ...(defaultValue.schemas as Extract<
+                    typeof defaultValue.schemas,
+                    Record<string, unknown>
+                  >),
+                  enabled:
+                    fields.schemas !== undefined
+                      ? Boolean(fields.schemas)
+                      : (
+                          defaultValue.schemas as Extract<
+                            typeof defaultValue.schemas,
+                            Record<string, unknown>
+                          >
+                        ).enabled,
+                },
+                mappers: {
+                  boolean: (enabled: boolean) => ({ enabled }),
+                },
+                value: fields.schemas,
               }),
             }),
           },

packages/shared/src/config/parser/types.ts

···
                 name?: NameTransformer;
               };
         };
+    /**
+     * Rename schema component keys and automatically update all `$ref` pointers
+     * throughout the specification.
+     *
+     * This is useful for:
+     * - Stripping version markers from schema names
+     * - Removing vendor prefixes
+     * - Converting naming conventions
+     * - Shortening verbose auto-generated names
+     *
+     * @example
+     * ```ts
+     * {
+     *   schemas: {
+     *     name: (name) => name.replace(/_v\d+_\d+_\d+_/, '_')
+     *   }
+     * }
+     * ```
+     *
+     * @default false
+     */
+    schemas?:
+      | boolean
+      | {
+          /**
+           * Whether this feature is enabled.
+           *
+           * @default false
+           */
+          enabled?: boolean;
+          /**
+           * Customize the generated name of schema components.
+           * When provided, this transformer is called for each schema key
+           * in `components.schemas` to compute the new name.
+           *
+           * If the new name conflicts with an existing schema, the rename
+           * is skipped for that schema.
+           *
+           * @default undefined
+           */
+          name?: NameTransformer;
+        };
   };
   /**
    * **This is an experimental feature.**
···
        * Configuration for generated response-specific schemas.
        */
       responses: NamingOptions;
+    };
+    /**
+     * Rename schema component keys and automatically update all `$ref` pointers
+     * throughout the specification.
+     */
+    schemas: FeatureToggle & {
+      /**
+       * Customize the generated name of schema components.
+       * When provided, this transformer is called for each schema key
+       * in `components.schemas` to compute the new name.
+       *
+       * If the new name conflicts with an existing schema, the rename
+       * is skipped for that schema.
+       *
+       * @default '{{name}}'
+       */
+      name: NameTransformer;
     };
   };
   /**

packages/shared/src/openApi/shared/transforms/index.ts

···
 import { enumsTransform } from './enums';
 import { propertiesRequiredByDefaultTransform } from './propertiesRequiredByDefault';
 import { readWriteTransform } from './readWrite';
+import { schemasTransform } from './schemas';
 
 export const transformOpenApiSpec = ({ context }: { context: Context }) => {
   const { logger } = context;
   const eventTransformOpenApiSpec = logger.timeEvent('transform-openapi-spec');
+
+  if (context.config.parser.transforms.schemas.enabled) {
+    schemasTransform({
+      config: context.config.parser.transforms.schemas,
+      spec: context.spec,
+    });
+  }
+
   if (context.config.parser.transforms.enums.enabled) {
     enumsTransform({
       config: context.config.parser.transforms.enums,

packages/shared/src/openApi/shared/transforms/schemas.ts

···
+import type { Parser } from '../../../config/parser/types';
+import { applyNaming } from '../../../utils/naming/naming';
+import { getSchemasObject } from '../utils/transforms';
+import { specToSchemasPointerNamespace } from './utils';
+
+type SchemasConfig = Parser['transforms']['schemas'];
+
+/**
+ * Recursively walks the entire spec object and replaces all $ref strings
+ * according to the provided rename mapping.
+ *
+ * @param node - Current node being visited
+ * @param renameMap - Map from old pointer to new pointer
+ */
+const rewriteRefs = (node: unknown, renameMap: Record<string, string>) => {
+  if (node instanceof Array) {
+    node.forEach((item) => rewriteRefs(item, renameMap));
+  } else if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref' && typeof value === 'string' && value in renameMap) {
+        // Replace the $ref with the new name
+        (node as Record<string, unknown>)[key] = renameMap[value];
+      } else {
+        rewriteRefs(value, renameMap);
+      }
+    }
+  }
+};
+
+/**
+ * Applies the schema name transform to rename schema component keys and
+ * update all $ref pointers throughout the spec.
+ *
+ * This transform:
+ * 1. Iterates all schema keys in components.schemas (or definitions for Swagger 2.0)
+ * 2. Applies the name transformer to compute new names
+ * 3. Handles name collisions (skips rename if new name already exists)
+ * 4. Renames schema keys in the schemas object
+ * 5. Updates all $ref pointers throughout the spec to use the new names
+ *
+ * @param config - The schemas transform config
+ * @param spec - The OpenAPI spec object to transform
+ */
+export const schemasTransform = ({ config, spec }: { config: SchemasConfig; spec: unknown }) => {
+  const schemasObj = getSchemasObject(spec);
+  if (!schemasObj) {
+    return;
+  }
+
+  const schemasPointerNamespace = specToSchemasPointerNamespace(spec);
+  if (!schemasPointerNamespace) {
+    return;
+  }
+
+  // Build rename map: oldPointer -> newPointer
+  const renameMap: Record<string, string> = {};
+  const newNames = new Set<string>();
+
+  // First pass: compute all new names and check for collisions
+  for (const oldName of Object.keys(schemasObj)) {
+    const newName = applyNaming(oldName, config);
+
+    // Skip if name doesn't change
+    if (newName === oldName) {
+      newNames.add(oldName);
+      continue;
+    }
+
+    // Skip if new name collides with an existing schema or another renamed schema
+    if (oldName in schemasObj && newName in schemasObj && oldName !== newName) {
+      // Collision with existing schema - skip rename
+      newNames.add(oldName);
+      continue;
+    }
+
+    if (newNames.has(newName)) {
+      // Collision with another renamed schema - skip rename
+      newNames.add(oldName);
+      continue;
+    }
+
+    // Record the rename
+    renameMap[`${schemasPointerNamespace}${oldName}`] = `${schemasPointerNamespace}${newName}`;
+    newNames.add(newName);
+  }
+
+  // Second pass: rename schema keys
+  // We need to be careful about the order to avoid overwriting
+  const renamedSchemas: Record<string, unknown> = {};
+  const processedOldNames = new Set<string>();
+
+  for (const [oldPointer, newPointer] of Object.entries(renameMap)) {
+    const oldName = oldPointer.slice(schemasPointerNamespace.length);
+    const newName = newPointer.slice(schemasPointerNamespace.length);
+
+    // Store the schema under the new name
+    renamedSchemas[newName] = schemasObj[oldName];
+    processedOldNames.add(oldName);
+  }
+
+  // Add all schemas that weren't renamed
+  for (const [name, schema] of Object.entries(schemasObj)) {
+    if (!processedOldNames.has(name)) {
+      renamedSchemas[name] = schema;
+    }
+  }
+
+  // Replace the entire schemas object with the renamed version
+  Object.keys(schemasObj).forEach((key) => delete schemasObj[key]);
+  Object.assign(schemasObj, renamedSchemas);
+
+  // Third pass: rewrite all $ref pointers throughout the spec
+  if (Object.keys(renameMap).length > 0) {
+    rewriteRefs(spec, renameMap);
+  }
+};