orval-labs
diff --git a/‎docs/content/docs/reference/configuration/output.mdx‎
Lines changed: 79 additions & 5 deletions b/‎docs/content/docs/reference/configuration/output.mdx‎
Lines changed: 79 additions & 5 deletions
diff --git a/‎packages/core/src/types.ts‎
Lines changed: 18 additions & 1 deletion b/‎packages/core/src/types.ts‎
Lines changed: 18 additions & 1 deletion
diff --git a/‎packages/core/src/utils/schemas-options.test.ts‎
Lines changed: 6 additions & 1 deletion b/‎packages/core/src/utils/schemas-options.test.ts‎
Lines changed: 6 additions & 1 deletion
diff --git a/‎packages/core/src/writers/generate-imports-for-builder.test.ts‎
Lines changed: 54 additions & 3 deletions b/‎packages/core/src/writers/generate-imports-for-builder.test.ts‎
Lines changed: 54 additions & 3 deletions
diff --git a/‎packages/core/src/writers/generate-imports-for-builder.ts‎
Lines changed: 17 additions & 1 deletion b/‎packages/core/src/writers/generate-imports-for-builder.ts‎
Lines changed: 17 additions & 1 deletion
diff --git a/‎packages/core/src/writers/index.ts‎
Lines changed: 2 additions & 0 deletions b/‎packages/core/src/writers/index.ts‎
Lines changed: 2 additions & 0 deletions
@@ -111,11 +111,12 @@ export default defineConfig({
 });
 ```
 
-| Property   | Type     | Description                                     |
-| ---------- | -------- | ----------------------------------------------- |
-| `path`     | `string` | Filesystem path for schema output               |
-| `type`     | `string` | `'typescript'` (default) or `'zod'` — optional |
-| `importPath` | `string` | Optional package import specifier (see below)  |
+| Property      | Type      | Description                                     |
+| ------------- | --------- | ----------------------------------------------- |
+| `path`        | `string`  | Filesystem path for schema output               |
+| `type`        | `string`  | `'typescript'` (default) or `'zod'` — optional |
+| `importPath`  | `string`  | Optional package import specifier (see below)   |
+| `splitByTags` | `boolean` | Organize schemas into per-tag subdirectories (default `false`, see below) |
 
 ### importPath
 
@@ -173,6 +174,57 @@ import statements change.
   relative, or absolute paths) before generation runs — see
   [Validation of `importPath`](#validation-of-importpath) below.
 
+### splitByTags
+
+When `splitByTags` is `true`, schemas are organized into per-tag
+subdirectories instead of a single flat directory. Schemas referenced by
+only one tag go in that tag's directory; schemas referenced by multiple
+tags (or not referenced by any operation) remain at the root of the schema
+directory. Works with any `mode` (`single`, `split`, `tags`, `tags-split`).
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      mode: 'tags-split',
+      schemas: {
+        path: './api/model',
+        splitByTags: true,
+      },
+    },
+  },
+});
+```
+
+Result:
+
+```
+api/model/
+├── error.ts               ← schemas used by 2+ tags (or unreferenced)
+├── pagination.ts
+├── pets/                  ← schemas only used by "pets" operations
+│   ├── pet.ts
+│   ├── createPetsBody.ts
+│   ├── listPetsParams.ts
+│   └── index.ts
+└── index.ts               ← root barrel re-exporting shared files + tag dirs
+```
+
+Cross-tag imports from within a tag subdirectory resolve to the parent:
+
+```ts
+// pets/pet.ts
+import type { Error } from '../error';
+```
+
+**Requirements:**
+
+- Works with any `mode` (`single`, `split`, `tags`, `tags-split`).
+- Incompatible with `operationSchemas` — operation-derived types are placed
+  within their tag directories automatically.
+- Schema-to-tag mapping is transitive: if `Pet` imports `Dog` which imports
+  `Dachshund`, all three land in the same directory.
+
 ### Validation of `importPath`
 
 During config normalization, orval rejects the following `importPath` values
@@ -352,6 +404,28 @@ my-app/src/
     └── users.ts             ← imports from ../models
 ```
 
+To organize schemas into per-tag subdirectories instead of a flat directory, use [`splitByTags`](#splitbytags):
+
+```
+my-app/src/
+├── models/
+│   ├── pagination.ts          ← shared schemas at root
+│   ├── error.ts
+│   ├── pets/
+│   │   ├── pet.ts
+│   │   ├── listPetsParams.ts
+│   │   └── index.ts
+│   ├── users/
+│   │   ├── user.ts
+│   │   ├── listUsersParams.ts
+│   │   └── index.ts
+│   └── index.ts               ← root barrel
+├── pets/
+│   └── pets.ts
+└── users/
+    └── users.ts
+```
+
 ## baseUrl
 
 **Type:** `String | Object`
 
@@ -36,7 +36,7 @@ export interface NormalizedOptions {
 export interface NormalizedOutputOptions {
   workspace?: string;
   target: string;
-  schemas?: string | SchemaOptions;
+  schemas?: string | NormalizedSchemaOptions;
   operationSchemas?: string;
   namingConvention: NamingConvention;
   fileExtension: string;
@@ -311,12 +311,21 @@ export interface SchemaOptions {
   path: string;
   type?: SchemaGenerationType;
   importPath?: string;
+  /**
+   * When `true`, schemas are organized into per-tag subdirectories instead of
+   * a single flat directory. Schemas referenced by multiple tags remain at the
+   * root of the schema directory.
+   *
+   * @default false
+   */
+  splitByTags?: boolean;
 }
 
 export interface NormalizedSchemaOptions {
   path: string;
   type: SchemaGenerationType;
   importPath?: string;
+  splitByTags: boolean;
 }
 
 export interface OutputOptions {
@@ -1783,6 +1792,14 @@ export interface WriteModeProps {
   header: string;
   needSchema: boolean;
   generateSchemasInline?: () => string;
+  // Schema-to-tag map computed by `writeSpecs` when `schemas.splitByTags` is
+  // enabled. Mode writers forward it to `generateImportsForBuilder` so the
+  // `indexFiles: false` branch can route each schema import into its tag
+  // subdirectory instead of assuming a flat layout. `undefined` when
+  // `splitByTags` is disabled, in which case routing falls back to the flat
+  // layout. The `'.'` sentinel marks schemas referenced by 0 or 2+ tags
+  // (shared, kept at the schemas root).
+  schemaTagMap?: Map<string, string>;
 }
 
 export interface GeneratorApiOperations {
 
@@ -9,13 +9,18 @@ describe('getSchemasImportPath', () => {
         path: '/libs/models',
         type: 'typescript',
         importPath: '@acme/models',
+        splitByTags: false,
       }),
     ).toBe('@acme/models');
   });
 
   it('returns undefined when schemas is an object without importPath', () => {
     expect(
-      getSchemasImportPath({ path: '/libs/models', type: 'typescript' }),
+      getSchemasImportPath({
+        path: '/libs/models',
+        type: 'typescript',
+        splitByTags: false,
+      }),
     ).toBeUndefined();
   });
 
 
@@ -122,7 +122,7 @@ describe('generateImportsForBuilder', () => {
       const output = createMockOutput({
         indexFiles: false,
         fileExtension: '.gen.ts',
-        schemas: { path: './schemas', type: 'zod' },
+        schemas: { path: './schemas', type: 'zod', splitByTags: false },
       });
       const imports = [createMockImport('User')];
 
@@ -140,7 +140,7 @@ describe('generateImportsForBuilder', () => {
       const output = createMockOutput({
         indexFiles: false,
         fileExtension: '.ts',
-        schemas: { path: './schemas', type: 'zod' },
+        schemas: { path: './schemas', type: 'zod', splitByTags: false },
       });
       const imports = [
         createMockImport('PortfolioResponseSchema', 'PortfolioResponse'),
@@ -184,7 +184,7 @@ describe('generateImportsForBuilder', () => {
       const output = createMockOutput({
         indexFiles: true,
         fileExtension: '.gen.ts',
-        schemas: { path: './schemas', type: 'zod' },
+        schemas: { path: './schemas', type: 'zod', splitByTags: false },
       });
       const imports = [createMockImport('User')];
 
@@ -208,6 +208,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
       });
       const imports = [createMockImport('User'), createMockImport('Pet')];
@@ -230,6 +231,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
       });
       const imports = [createMockImport('User'), createMockImport('Pet')];
@@ -262,6 +264,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
       });
       const imports = [createMockImport('User')];
@@ -284,6 +287,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'zod',
           importPath: '@acme/models',
+          splitByTags: false,
         },
       });
       const imports = [createMockImport('User')];
@@ -306,6 +310,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
       });
       const imports: GeneratorImport[] = [
@@ -330,6 +335,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
         mock: {
           indexMockFiles: false,
@@ -368,6 +374,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
         mock: {
           indexMockFiles: false,
@@ -426,4 +433,48 @@ describe('generateImportsForBuilder', () => {
       ]);
     });
   });
+
+  describe('splitByTags routing', () => {
+    // `buildSchemaTagMap` keys on `schema.name`, which is the pascal-cased
+    // TS identifier produced by `getRefInfo`. The lookup here must use
+    // `schemaImport.name` (same identifier), not `schemaName` (the original
+    // `components.schemas` key). When they differ, routing by `schemaName`
+    // silently misses the map and places the import at the schemas root
+    // instead of the tag subdirectory.
+    it('routes by the TS identifier (name), not schemaName, when they differ', () => {
+      const output = createMockOutput({ indexFiles: false });
+      // `name: 'Pet'` is the TS identifier the map is keyed by.
+      // `schemaName: 'PetSchema'` is the original components.schemas key.
+      // The tag dir ('pets') must come from looking up `Pet`, not `PetSchema`
+      // (which would miss the map and produce no tag segment).
+      const imports = [createMockImport('Pet', 'PetSchema')];
+      const schemaTagMap = new Map<string, string>([['Pet', 'pets']]);
+
+      const result = generateImportsForBuilder(
+        output,
+        imports,
+        '../models',
+        schemaTagMap,
+      );
+
+      expect(result).toHaveProperty('0.dependency', '../models/pets/petSchema');
+    });
+
+    it('inserts the tag subdir for matched schemas and leaves unmatched at root', () => {
+      const output = createMockOutput({ indexFiles: false });
+      // `Pet` is in the map; `Error` is not. Only `Pet` gets the tag segment.
+      const imports = [createMockImport('Pet'), createMockImport('Error')];
+      const schemaTagMap = new Map<string, string>([['Pet', 'pets']]);
+
+      const result = generateImportsForBuilder(
+        output,
+        imports,
+        '../models',
+        schemaTagMap,
+      );
+
+      const deps = result.map((r) => r.dependency).sort();
+      expect(deps).toEqual(['../models/error', '../models/pets/pet']);
+    });
+  });
 });
@@ -20,6 +20,11 @@ export function generateImportsForBuilder(
   output: NormalizedOutputOptions,
   imports: readonly GeneratorImport[],
   relativeSchemasPath: string,
+  // Schema→tag map computed by `writeSpecs` when `schemas.splitByTags` is
+  // enabled. Used only in the `indexFiles: false` branch to insert each
+  // schema's tag subdirectory into the import path. `'.'` is the sentinel
+  // for shared schemas (referenced by 0 or 2+ tags).
+  schemaTagMap?: Map<string, string>,
 ): GeneratorDependency[] {
   const isPackageImport =
     isObject(output.schemas) && !!output.schemas.importPath;
@@ -93,9 +98,20 @@ export function generateImportsForBuilder(
       const importExtension = isPackageImport
         ? ''
         : getImportExtension(output.fileExtension, output.tsconfig);
+      // When schemas are split by tag, route each import into its tag
+      // subdirectory. Schemas referenced by 0 or 2+ tags land at the schemas
+      // root (sentinel `'.'`); their path is unchanged from the flat layout.
+      // The lookup uses the TS identifier (`schemaImport.name`), not
+      // `schemaName`, because `buildSchemaTagMap` keys on `schema.name`
+      // which is the pascal-cased TS identifier produced by `getRefInfo`.
+      // `baseName` (which prefers `schemaName`) is only correct for the
+      // filename computation below, where `conventionName` happens to be
+      // idempotent on already-pascal-cased input.
+      const tagDir = schemaTagMap?.get(schemaImport.name);
+      const tagSegment = tagDir && tagDir !== '.' ? `${tagDir}/` : '';
       const dependency = upath.joinSafe(
         relativeSchemasPath,
-        `${normalizedName}${suffix}${importExtension}`,
+        `${tagSegment}${normalizedName}${suffix}${importExtension}`,
       );
 
       if (!importsByDependency.has(dependency)) {
 
@@ -1,5 +1,7 @@
 export * from './file';
+export * from './schema-tag-mapper';
 export * from './schemas';
+export * from './schemas-tags-split';
 export * from './single-mode';
 export * from './split-mode';
 export * from './split-tags-mode';