0
# Schema Transforms
1

2
Schema transform functions convert individual OpenAPI specification objects into TypeScript AST nodes. These modular functions handle different parts of the OpenAPI document and can be used independently for custom processing workflows.
3

4
## Capabilities
5

6
### Main Schema Transform
7

8
Orchestrates the transformation of a complete OpenAPI document by delegating to specialized transform functions.
9

10
```typescript { .api }
11
/**
12
 * Transform an entire OpenAPI schema to TypeScript AST nodes
13
 * @param schema - Complete OpenAPI 3.0/3.1 document
14
 * @param ctx - Global transformation context with options
15
 * @returns Array of TypeScript AST nodes representing the complete schema
16
 */
17
function transformSchema(schema: OpenAPI3, ctx: GlobalContext): ts.Node[];
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { transformSchema, astToString } from "openapi-typescript";
24

25
// Assume you have a parsed OpenAPI schema and context
26
const ast = transformSchema(openApiSchema, globalContext);
27
const output = astToString(ast);
28
```
29

30
### Schema Object Transform
31

32
Converts individual JSON Schema objects to TypeScript type nodes with full support for composition, validation, and advanced features.
33

34
```typescript { .api }
35
/**
36
 * Transform a Schema Object or Reference to TypeScript type
37
 * @param schemaObject - Schema Object or Reference Object from OpenAPI
38
 * @param options - Transform options with path context
39
 * @returns TypeScript type node representing the schema
40
 */
41
function transformSchemaObject(
42
  schemaObject: SchemaObject | ReferenceObject,
43
  options: TransformNodeOptions
44
): ts.TypeNode;
45

46
/**
47
 * Transform Schema Object with composition support (allOf, anyOf, oneOf)
48
 * @param schemaObject - Schema Object with composition keywords
49
 * @param options - Transform options with path context
50
 * @returns TypeScript type node handling composition
51
 */
52
function transformSchemaObjectWithComposition(
53
  schemaObject: SchemaObject,
54
  options: TransformNodeOptions
55
): ts.TypeNode;
56
```
57

58
**Supported Schema Features:**
59
- All JSON Schema types (string, number, object, array, boolean, null)
60
- Composition keywords (`allOf`, `anyOf`, `oneOf`)
61
- String formats and patterns
62
- Number constraints (minimum, maximum, multipleOf)
63
- Array constraints (minItems, maxItems, uniqueItems)
64
- Object properties and additional properties
65
- Enums and const values
66
- Nullable and default values
67
- Discriminators for polymorphism
68

69
**Usage Examples:**
70

71
```typescript
72
import { transformSchemaObject } from "openapi-typescript";
73

74
// Simple schema transform
75
const stringSchema = { type: "string", format: "email" };
76
const typeNode = transformSchemaObject(stringSchema, {
77
  path: "#/components/schemas/Email",
78
  ctx: globalContext,
79
  schema: openApiDocument
80
});
81

82
// Object schema with properties
83
const userSchema = {
84
  type: "object",
85
  properties: {
86
    id: { type: "string" },
87
    name: { type: "string" },
88
    email: { type: "string", format: "email" }
89
  },
90
  required: ["id", "name"]
91
};
92
const userType = transformSchemaObject(userSchema, options);
93

94
// Schema with composition
95
const compositeSchema = {
96
  allOf: [
97
    { $ref: "#/components/schemas/BaseUser" },
98
    {
99
      type: "object",
100
      properties: {
101
        role: { type: "string", enum: ["admin", "user"] }
102
      }
103
    }
104
  ]
105
};
106
const compositeType = transformSchemaObjectWithComposition(compositeSchema, options);
107
```
108

109
### Components Object Transform
110

111
Transforms the OpenAPI Components Object containing reusable schemas, responses, parameters, and other components.
112

113
```typescript { .api }
114
/**
115
 * Transform Components Object to TypeScript declarations
116
 * @param componentsObject - OpenAPI Components Object
117
 * @param ctx - Global transformation context
118
 * @returns Array of TypeScript nodes for all components
119
 */
120
function transformComponentsObject(
121
  componentsObject: ComponentsObject,
122
  ctx: GlobalContext
123
): ts.Node[];
124
```
125

126
**Handles Components:**
127
- `schemas` - Reusable schema definitions
128
- `responses` - Reusable response definitions
129
- `parameters` - Reusable parameter definitions
130
- `requestBodies` - Reusable request body definitions
131
- `headers` - Reusable header definitions
132
- `pathItems` - Reusable path item definitions
133

134
**Usage Example:**
135

136
```typescript
137
import { transformComponentsObject } from "openapi-typescript";
138

139
const components = {
140
  schemas: {
141
    User: {
142
      type: "object",
143
      properties: {
144
        id: { type: "string" },
145
        name: { type: "string" }
146
      }
147
    },
148
    Product: {
149
      type: "object",
150
      properties: {
151
        id: { type: "string" },
152
        name: { type: "string" },
153
        price: { type: "number" }
154
      }
155
    }
156
  }
157
};
158

159
const componentNodes = transformComponentsObject(components, globalContext);
160
```
161

162
### Paths Object Transform
163

164
Converts the OpenAPI Paths Object containing all API endpoints to TypeScript interfaces.
165

166
```typescript { .api }
167
/**
168
 * Transform Paths Object to TypeScript interface
169
 * @param pathsObject - OpenAPI Paths Object with all endpoints
170
 * @param ctx - Global transformation context
171
 * @returns TypeScript type node representing all paths
172
 */
173
function transformPathsObject(
174
  pathsObject: PathsObject,
175
  ctx: GlobalContext
176
): ts.TypeNode;
177
```
178

179
**Features:**
180
- Supports all HTTP methods (GET, POST, PUT, DELETE, etc.)
181
- Handles path parameters with template literal types
182
- Processes operation parameters and request/response bodies
183
- Supports operation IDs for named operations
184

185
**Usage Example:**
186

187
```typescript
188
import { transformPathsObject } from "openapi-typescript";
189

190
const paths = {
191
  "/users": {
192
    get: {
193
      responses: {
194
        "200": {
195
          description: "List of users",
196
          content: {
197
            "application/json": {
198
              schema: { $ref: "#/components/schemas/User" }
199
            }
200
          }
201
        }
202
      }
203
    }
204
  },
205
  "/users/{id}": {
206
    get: {
207
      parameters: [
208
        {
209
          name: "id",
210
          in: "path",
211
          required: true,
212
          schema: { type: "string" }
213
        }
214
      ]
215
    }
216
  }
217
};
218

219
const pathsType = transformPathsObject(paths, globalContext);
220
```
221

222
### Path Item Object Transform
223

224
Transforms individual Path Item Objects containing operations for a specific path.
225

226
```typescript { .api }
227
/**
228
 * Transform Path Item Object to TypeScript type
229
 * @param pathItem - OpenAPI Path Item Object
230
 * @param options - Transform options with path context
231
 * @returns TypeScript type node for the path item
232
 */
233
function transformPathItemObject(
234
  pathItem: PathItemObject,
235
  options: TransformNodeOptions
236
): ts.TypeNode;
237

238
/**
239
 * HTTP method type union
240
 */
241
type Method = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
242
```
243

244
### Operation Object Transform
245

246
Transforms HTTP Operation Objects to TypeScript type elements.
247

248
```typescript { .api }
249
/**
250
 * Transform Operation Object to TypeScript type elements
251
 * @param operationObject - OpenAPI Operation Object
252
 * @param options - Transform options with path context
253
 * @returns Array of TypeScript type elements for the operation
254
 */
255
function transformOperationObject(
256
  operationObject: OperationObject,
257
  options: TransformNodeOptions
258
): ts.TypeElement[];
259

260
/**
261
 * Inject operation objects into a top-level operations interface
262
 * @param operations - Map of operation ID to type elements
263
 * @param ctx - Global transformation context
264
 * @returns TypeScript interface declaration for operations
265
 */
266
function injectOperationObject(
267
  operations: Record<string, ts.TypeElement[]>,
268
  ctx: GlobalContext
269
): ts.InterfaceDeclaration;
270
```
271

272
### Response Transform Functions
273

274
Functions for transforming response-related OpenAPI objects.
275

276
```typescript { .api }
277
/**
278
 * Transform Response Object to TypeScript type
279
 * @param responseObject - OpenAPI Response Object
280
 * @param options - Transform options with path context
281
 * @returns TypeScript type node for the response
282
 */
283
function transformResponseObject(
284
  responseObject: ResponseObject,
285
  options: TransformNodeOptions
286
): ts.TypeNode;
287

288
/**
289
 * Transform Responses Object container to TypeScript type
290
 * @param responsesObject - OpenAPI Responses Object
291
 * @param options - Transform options with path context
292
 * @returns TypeScript type node for all responses
293
 */
294
function transformResponsesObject(
295
  responsesObject: ResponsesObject,
296
  options: TransformNodeOptions
297
): ts.TypeNode;
298
```
299

300
### Request Body Transform
301

302
Transforms Request Body Objects to TypeScript types.
303

304
```typescript { .api }
305
/**
306
 * Transform Request Body Object to TypeScript type
307
 * @param requestBodyObject - OpenAPI Request Body Object
308
 * @param options - Transform options with path context
309
 * @returns TypeScript type node for the request body
310
 */
311
function transformRequestBodyObject(
312
  requestBodyObject: RequestBodyObject,
313
  options: TransformNodeOptions
314
): ts.TypeNode;
315
```
316

317
### Parameter Transform Functions
318

319
Functions for transforming parameter-related objects.
320

321
```typescript { .api }
322
/**
323
 * Transform Parameter Object to TypeScript type
324
 * @param parameterObject - OpenAPI Parameter Object
325
 * @param options - Transform options with path context
326
 * @returns TypeScript type node for the parameter
327
 */
328
function transformParameterObject(
329
  parameterObject: ParameterObject,
330
  options: TransformNodeOptions
331
): ts.TypeNode;
332

333
/**
334
 * Transform array of parameters to structured type elements
335
 * @param parametersArray - Array of Parameter Objects or References
336
 * @param options - Transform options with path context
337
 * @returns Array of TypeScript type elements grouped by parameter location
338
 */
339
function transformParametersArray(
340
  parametersArray: (ParameterObject | ReferenceObject)[],
341
  options: TransformNodeOptions
342
): ts.TypeElement[];
343
```
344

345
### Header and Media Type Transforms
346

347
Additional transform functions for specific OpenAPI objects.
348

349
```typescript { .api }
350
/**
351
 * Transform Header Object to TypeScript type
352
 * @param headerObject - OpenAPI Header Object
353
 * @param options - Transform options with path context
354
 * @returns TypeScript type node for the header
355
 */
356
function transformHeaderObject(
357
  headerObject: HeaderObject,
358
  options: TransformNodeOptions
359
): ts.TypeNode;
360

361
/**
362
 * Transform Media Type Object to TypeScript type
363
 * @param mediaTypeObject - OpenAPI Media Type Object
364
 * @param options - Transform options with path context
365
 * @returns TypeScript type node for the media type
366
 */
367
function transformMediaTypeObject(
368
  mediaTypeObject: MediaTypeObject,
369
  options: TransformNodeOptions
370
): ts.TypeNode;
371
```
372

373
### Webhooks Transform
374

375
Transforms OpenAPI 3.1 Webhooks Objects.
376

377
```typescript { .api }
378
/**
379
 * Transform Webhooks Object to TypeScript type (OpenAPI 3.1)
380
 * @param webhooksObject - OpenAPI Webhooks Object
381
 * @param options - Global transformation context
382
 * @returns TypeScript type node for webhooks
383
 */
384
function transformWebhooksObject(
385
  webhooksObject: WebhooksObject,
386
  options: GlobalContext
387
): ts.TypeNode;
388
```
389

390
### Utility Transform Functions
391

392
Additional utilities for specific transform scenarios.
393

394
```typescript { .api }
395
/**
396
 * Create API paths enum when --make-paths-enum is enabled
397
 * @param pathsObject - OpenAPI Paths Object
398
 * @returns TypeScript enum declaration for all paths
399
 */
400
function makeApiPathsEnum(pathsObject: PathsObject): ts.EnumDeclaration;
401

402
/**
403
 * Check if schema object represents an enum type
404
 * @param schema - Schema object to check
405
 * @returns True if schema should generate enum vs type alias
406
 */
407
function isEnumSchema(schema: unknown): boolean;
408

409
/**
410
 * Convert component collection names to singular form
411
 * @param key - Component key (e.g., "schemas", "responses")
412
 * @returns Singular form of the key
413
 */
414
function singularizeComponentKey(key: string): string;
415
```
416

417
**Usage Example:**
418

419
```typescript
420
import { makeApiPathsEnum, transformPathsObject } from "openapi-typescript";
421

422
// Generate paths enum
423
const pathsEnum = makeApiPathsEnum(pathsObject);
424

425
// Check if schema should be an enum
426
const shouldBeEnum = isEnumSchema(schemaObject);
427

428
// Convert collection key
429
const singular = singularizeComponentKey("schemas"); // "schema"
430
```