feat(core): add schemas.importPath for package import specifiers (#3535)

Allow generated client files to import schema types from a package
specifier (e.g. '@acme/models') instead of computing a relative
filesystem path. This unblocks use cases where the schemas and client
outputs sit in separate TypeScript compilation roots or in
secondary entrypoint packages.

When `schemas.importPath` is set, all four write modes and the
factory generators emit imports from the configured package
specifier. The filesystem `path` is still used for the on-disk
schema output, and validation rejects empty strings, relative paths,
absolute paths, and whitespace-only values.

- core: add `importPath` to `SchemaOptions` / `NormalizedSchemaOptions`
- core: extract `getSchemasImportPath` helper into its own module
- core: update all writers (single/split/tags/split-tags) to use the helper
- core: update factory.ts to resolve factory and type imports from `importPath`
- core: skip per-file extension in `generateImportsForBuilder` for package imports
- orval: tighten `normalizeSchemasOption` validation for `importPath`
- docs: document `schemas` object form and `importPath` requirements
- tests: cover all four modes, zod suffix, faker subpath, and
  `outputDirectory` bypass

Closes #3535

Author: aqeelat

docs/content/docs/reference/configuration/output.mdx

@@ -79,10 +79,12 @@ export default defineConfig({
 
 ## schemas
 
-**Type:** `String`
+**Type:** `String | Object | false`
 **Default:** Same as `target`
 
-Output path for generated model types.
+Output path for generated model types. Set to `false` to disable separate schema file output.
+
+### String form
 
 ```ts title="orval.config.ts"
 export default defineConfig({
@@ -94,6 +96,77 @@ export default defineConfig({
 });
 ```
 
+### Object form
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      schemas: {
+        path: './api/model',
+        type: 'typescript', // 'typescript' | 'zod'
+      },
+    },
+  },
+});
+```
+
+| Property   | Type     | Description                                     |
+| ---------- | -------- | ----------------------------------------------- |
+| `path`     | `string` | Filesystem path for schema output               |
+| `type`     | `string` | `'typescript'` or `'zod'`                       |
+| `importPath` | `string` | Optional package import specifier (see below)  |
+
+### importPath
+
+When `importPath` is set, generated client files import schema types from
+that package specifier instead of computing a relative filesystem path:
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      target: './libs/client/angular/src/lib/endpoints',
+      schemas: {
+        path: './libs/client/models/src/lib',
+        type: 'typescript',
+        importPath: '@acme/client/models',
+      },
+    },
+  },
+});
+```
+
+```ts
+// Without importPath — computed relative path:
+import type { Pet } from '../models/pet';
+
+// With importPath: '@acme/client/models':
+import type { Pet } from '@acme/client/models';
+```
+
+Schemas are still written to the filesystem `path` — only the generated
+import statements change.
+
+**Requirements when using `importPath`:**
+
+- The target package must export the types at the specified import path.
+- With `indexFiles: true` (recommended), all types are imported from the
+  single `importPath` (e.g., `@acme/models`).
+- With `indexFiles: false`, each schema is imported individually
+  (e.g., `@acme/models/pet`). The package must support these subpath exports.
+  For Zod schemas (`type: 'zod'`) the per-file suffix is `.zod`, so the
+  package must also expose `./pet.zod` (e.g., `@acme/models/pet.zod`).
+- If using faker schema factories
+  (`mock: { generators: [{ type: 'faker', schemas: true }] }`),
+  the package must also export `./index.faker`.
+- If using factory methods (`factoryMethods`), each schema is imported
+  individually regardless of `indexFiles`.
+- When `importPath` is set, the relative-path computation in
+  `factoryMethods.outputDirectory` is bypassed: factories resolve imports
+  against the package specifier rather than the on-disk factory output
+  directory.
+
 ## operationSchemas
 
 **Type:** `String`

packages/core/src/generators/factory.test.ts

@@ -611,3 +611,168 @@ describe('generateFactory', () => {
     );
   });
 });
+
+describe('generateFactory with schemas.importPath', () => {
+  it('uses importPath for $ref imports in split mode', () => {
+    const schema: OpenApiSchemaObject = {
+      type: 'object',
+      required: ['target'],
+      properties: {
+        target: { $ref: '#/components/schemas/RefTarget' },
+      },
+    };
+
+    const result = generateFactory(
+      schema,
+      'WithRef',
+      createMockContext({
+        factoryMethods: { ...baseFactoryMethods, mode: 'split' },
+        schemas: {
+          path: '/libs/models',
+          type: 'typescript',
+          importPath: '@acme/models',
+        },
+      }),
+    );
+    expect(result?.imports).toContainEqual({
+      name: 'createRefTarget',
+      importPath: '@acme/models/refTarget',
+      isConstant: true,
+    });
+    expect(result?.imports).toContainEqual({
+      name: 'RefTarget',
+      importPath: '@acme/models/refTarget',
+    });
+  });
+
+  it('uses importPath for circular reference casts in split mode', () => {
+    const schema: OpenApiSchemaObject = {
+      type: 'object',
+      required: ['child'],
+      properties: {
+        child: { $ref: '#/components/schemas/CircularChild' },
+      },
+    };
+
+    const result = generateFactory(
+      schema,
+      'CircularParent',
+      createMockContext({
+        factoryMethods: { ...baseFactoryMethods, mode: 'split' },
+        schemas: {
+          path: '/libs/models',
+          type: 'typescript',
+          importPath: '@acme/models',
+        },
+      }),
+    );
+    expect(result?.model).toContain('child: {} as CircularChild');
+    expect(result?.imports).toContainEqual({
+      name: 'CircularChild',
+      importPath: '@acme/models/circularChild',
+    });
+    expect(result?.imports).toContainEqual({
+      name: 'CircularParent',
+      importPath: '@acme/models/circularParent',
+    });
+  });
+
+  it('uses importPath for factory function imports in single mode', () => {
+    const schema: OpenApiSchemaObject = {
+      type: 'object',
+      required: ['target'],
+      properties: {
+        target: { $ref: '#/components/schemas/RefTarget' },
+      },
+    };
+
+    const result = generateFactory(
+      schema,
+      'WithRef',
+      createMockContext({
+        factoryMethods: { ...baseFactoryMethods, mode: 'single' },
+        schemas: {
+          path: '/libs/models',
+          type: 'typescript',
+          importPath: '@acme/models',
+        },
+      }),
+    );
+    expect(result?.imports).toContainEqual({
+      name: 'createRefTarget',
+      importPath: '@acme/models/refTarget',
+      isConstant: true,
+    });
+  });
+
+  it('uses importPath for type imports in single-split mode (factory combined into single file)', () => {
+    const schema: OpenApiSchemaObject = {
+      type: 'object',
+      required: ['target'],
+      properties: {
+        target: { $ref: '#/components/schemas/RefTarget' },
+      },
+    };
+
+    const result = generateFactory(
+      schema,
+      'WithRefCombined',
+      createMockContext({
+        factoryMethods: { ...baseFactoryMethods, mode: 'single-split' },
+        schemas: {
+          path: '/libs/models',
+          type: 'typescript',
+          importPath: '@acme/models',
+        },
+      }),
+    );
+    expect(result?.imports).not.toContainEqual(
+      expect.objectContaining({ name: 'createRefTarget' }),
+    );
+    expect(result?.imports).toContainEqual({
+      name: 'RefTarget',
+      importPath: '@acme/models/refTarget',
+    });
+    expect(result?.imports).toContainEqual({
+      name: 'WithRefCombined',
+      importPath: '@acme/models/withRefCombined',
+    });
+  });
+
+  it('bypasses factoryMethods.outputDirectory when importPath is set (split mode)', () => {
+    const schema: OpenApiSchemaObject = {
+      type: 'object',
+      required: ['target'],
+      properties: {
+        target: { $ref: '#/components/schemas/RefTarget' },
+      },
+    };
+
+    const result = generateFactory(
+      schema,
+      'WithRef',
+      createMockContext({
+        factoryMethods: {
+          ...baseFactoryMethods,
+          mode: 'split',
+          outputDirectory: '/libs/factories',
+        },
+        schemas: {
+          path: '/libs/models',
+          type: 'typescript',
+          importPath: '@acme/models',
+        },
+      }),
+    );
+
+    const factoryImport = result?.imports.find(
+      (i) => i.name === 'createRefTarget',
+    );
+    expect(factoryImport?.importPath).toBe('@acme/models/refTarget');
+    expect(factoryImport?.importPath).not.toContain('factories');
+
+    const typeImport = result?.imports.find((i) => i.name === 'RefTarget');
+    expect(typeImport?.importPath).toBe('@acme/models/refTarget');
+    expect(typeImport?.importPath).not.toContain('factories');
+  });
+});

packages/core/src/generators/factory.ts

@@ -9,6 +9,7 @@ import { PropertySortOrder } from '../types';
 import {
   conventionName,
   getFileInfo,
+  getSchemasImportPath,
   isString,
   logWarning,
   pascal,
@@ -34,6 +35,13 @@ function getSchemaImportPath(
   if (context.output.factoryMethods?.mode === 'single') {
     return undefined;
   }
+
+  const importPathBase = getSchemasImportPath(context.output.schemas);
+  if (importPathBase) {
+    const baseName = conventionName(refName, context.output.namingConvention);
+    return upath.joinSafe(importPathBase, baseName);
+  }
+
   let outputDir = context.output.factoryMethods?.outputDirectory;
   let schemasPath = getSchemasPath(context);
 
@@ -328,15 +336,24 @@ function resolveImportPath(
   context: ContextSpec,
 ): string | undefined {
   const baseName = conventionName(refName, context.output.namingConvention);
+  const pkgBase = getSchemasImportPath(context.output.schemas);
+
   switch (mode) {
     case 'split': {
-      return `./${baseName}.factory`;
+      return pkgBase
+        ? upath.joinSafe(pkgBase, baseName)
+        : `./${baseName}.factory`;
     }
     case 'single-split': {
-      return `./${conventionName('factoryMethods', context.output.namingConvention)}`;
+      return pkgBase
+        ? upath.joinSafe(
+            pkgBase,
+            conventionName('factoryMethods', context.output.namingConvention),
+          )
+        : `./${conventionName('factoryMethods', context.output.namingConvention)}`;
     }
     case 'single': {
-      return `./${baseName}`;
+      return pkgBase ? upath.joinSafe(pkgBase, baseName) : `./${baseName}`;
     }
   }
 }

packages/core/src/types.ts

@@ -308,11 +308,13 @@ export interface NormalizedFactoryMethodsOptions {
 export interface SchemaOptions {
   path: string;
   type: SchemaGenerationType;
+  importPath?: string;
 }
 
 export interface NormalizedSchemaOptions {
   path: string;
   type: SchemaGenerationType;
+  importPath?: string;
 }
 
 export interface OutputOptions {

packages/core/src/utils/assertion.test.ts

@@ -23,6 +23,7 @@ describe('assertion testing', () => {
   it('checks for reference objects', () => {
     expect(isReference({ $ref: '#/components/schemas/User' })).toBeTruthy();
     expect(isReference({} as Record<string, unknown>)).toBeFalsy();
+    expect(isReference({ $dynamicRef: '#category' })).toBeFalsy();
     // eslint-disable-next-line unicorn/no-null -- testing null handling
     expect(isReference(null as unknown as object)).toBeFalsy();
   });
@@ -136,10 +137,6 @@ describe('isDynamicReference', () => {
     );
   });
 
-  it('returns false for objects with $dynamicRef but not $ref in isReference', () => {
-    expect(isReference({ $dynamicRef: '#category' })).toBe(false);
-  });
-
   it('returns true for objects with $ref in isReference', () => {
     expect(isReference({ $ref: '#/components/schemas/Foo' })).toBe(true);
   });

packages/core/src/utils/index.ts

@@ -17,6 +17,7 @@ export * from './merge-deep';
 export * from './occurrence';
 export * as upath from './path';
 export * from './resolve-version';
+export * from './schemas-options';
 export * from './sort';
 export * from './string';
 export * from './tsconfig';

packages/core/src/utils/schemas-options.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { getSchemasImportPath } from './schemas-options';
+
+describe('getSchemasImportPath', () => {
+  it('returns importPath when schemas is an object with importPath', () => {
+    expect(
+      getSchemasImportPath({
+        path: '/libs/models',
+        type: 'typescript',
+        importPath: '@acme/models',
+      }),
+    ).toBe('@acme/models');
+  });
+
+  it('returns undefined when schemas is an object without importPath', () => {
+    expect(
+      getSchemasImportPath({ path: '/libs/models', type: 'typescript' }),
+    ).toBeUndefined();
+  });
+
+  it('returns undefined when schemas is a string', () => {
+    expect(getSchemasImportPath('./models')).toBeUndefined();
+  });
+
+  it('returns undefined when schemas is undefined', () => {
+    expect(getSchemasImportPath()).toBeUndefined();
+  });
+
+  it('returns undefined when schemas is false', () => {
+    expect(getSchemasImportPath(false)).toBeUndefined();
+  });
+});