0
# OpenAPI 3.0 Types
1

2
Complete TypeScript interfaces for all OpenAPI 3.0 specification components including schemas, operations, and security definitions.
3

4
## Capabilities
5

6
### Core Document Interfaces
7

8
Main interfaces for the OpenAPI document structure.
9

10
```typescript { .api }
11
/**
12
 * Root OpenAPI 3.0 document object
13
 */
14
interface OpenAPIObject extends ISpecificationExtension {
15
  openapi: string;
16
  info: InfoObject;
17
  servers?: ServerObject[];
18
  paths: PathsObject;
19
  components?: ComponentsObject;
20
  security?: SecurityRequirementObject[];
21
  tags?: TagObject[];
22
  externalDocs?: ExternalDocumentationObject;
23
}
24

25
/**
26
 * API metadata information
27
 */
28
interface InfoObject extends ISpecificationExtension {
29
  title: string;
30
  description?: string;
31
  termsOfService?: string;
32
  contact?: ContactObject;
33
  license?: LicenseObject;
34
  version: string;
35
}
36

37
/**
38
 * Contact information for the API
39
 */
40
interface ContactObject extends ISpecificationExtension {
41
  name?: string;
42
  url?: string;
43
  email?: string;
44
}
45

46
/**
47
 * License information for the API
48
 */
49
interface LicenseObject extends ISpecificationExtension {
50
  name: string;
51
  url?: string;
52
}
53
```
54

55
### Component Container Interface
56

57
Interface for reusable OpenAPI components.
58

59
```typescript { .api }
60
/**
61
 * Container for reusable components
62
 */
63
interface ComponentsObject extends ISpecificationExtension {
64
  schemas?: { [schema: string]: SchemaObject | ReferenceObject };
65
  responses?: { [response: string]: ResponseObject | ReferenceObject };
66
  parameters?: { [parameter: string]: ParameterObject | ReferenceObject };
67
  examples?: { [example: string]: ExampleObject | ReferenceObject };
68
  requestBodies?: { [request: string]: RequestBodyObject | ReferenceObject };
69
  headers?: { [header: string]: HeaderObject | ReferenceObject };
70
  securitySchemes?: { [securityScheme: string]: SecuritySchemeObject | ReferenceObject };
71
  links?: { [link: string]: LinkObject | ReferenceObject };
72
  callbacks?: { [callback: string]: CallbackObject | ReferenceObject };
73
}
74
```
75

76
### Path and Operation Interfaces
77

78
Interfaces for defining API paths and operations.
79

80
```typescript { .api }
81
/**
82
 * Container for API paths (renamed from PathObject for spec consistency)
83
 */
84
interface PathsObject extends ISpecificationExtension {
85
  [path: string]: PathItemObject;
86
}
87

88
/**
89
 * @deprecated Use PathsObject instead
90
 */
91
type PathObject = PathsObject;
92

93
/**
94
 * Single path item with HTTP operations
95
 */
96
interface PathItemObject extends ISpecificationExtension {
97
  $ref?: string;
98
  summary?: string;
99
  description?: string;
100
  get?: OperationObject;
101
  put?: OperationObject;
102
  post?: OperationObject;
103
  delete?: OperationObject;
104
  options?: OperationObject;
105
  head?: OperationObject;
106
  patch?: OperationObject;
107
  trace?: OperationObject;
108
  servers?: ServerObject[];
109
  parameters?: (ParameterObject | ReferenceObject)[];
110
}
111

112
/**
113
 * HTTP operation definition
114
 */
115
interface OperationObject extends ISpecificationExtension {
116
  tags?: string[];
117
  summary?: string;
118
  description?: string;
119
  externalDocs?: ExternalDocumentationObject;
120
  operationId?: string;
121
  parameters?: (ParameterObject | ReferenceObject)[];
122
  requestBody?: RequestBodyObject | ReferenceObject;
123
  responses: ResponsesObject;
124
  callbacks?: CallbacksObject;
125
  deprecated?: boolean;
126
  security?: SecurityRequirementObject[];
127
  servers?: ServerObject[];
128
}
129

130
/**
131
 * External documentation reference
132
 */
133
interface ExternalDocumentationObject extends ISpecificationExtension {
134
  description?: string;
135
  url: string;
136
}
137
```
138

139
### Parameter Interfaces
140

141
Interfaces for defining API parameters.
142

143
```typescript { .api }
144
/**
145
 * Parameter location type
146
 */
147
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
148

149
/**
150
 * Parameter serialization style
151
 */
152
type ParameterStyle =
153
  | 'matrix'
154
  | 'label' 
155
  | 'form'
156
  | 'simple'
157
  | 'spaceDelimited'
158
  | 'pipeDelimited'
159
  | 'deepObject';
160

161
/**
162
 * Base parameter properties
163
 */
164
interface BaseParameterObject extends ISpecificationExtension {
165
  description?: string;
166
  required?: boolean;
167
  deprecated?: boolean;
168
  allowEmptyValue?: boolean;
169
  style?: ParameterStyle;
170
  explode?: boolean;
171
  allowReserved?: boolean;
172
  schema?: SchemaObject | ReferenceObject;
173
  examples?: { [param: string]: ExampleObject | ReferenceObject };
174
  example?: any;
175
  content?: ContentObject;
176
}
177

178
/**
179
 * Complete parameter definition
180
 */
181
interface ParameterObject extends BaseParameterObject {
182
  name: string;
183
  in: ParameterLocation;
184
}
185
```
186

187
### Request and Response Interfaces
188

189
Interfaces for request bodies and responses.
190

191
```typescript { .api }
192
/**
193
 * Request body definition
194
 */
195
interface RequestBodyObject extends ISpecificationExtension {
196
  description?: string;
197
  content: ContentObject;
198
  required?: boolean;
199
}
200

201
/**
202
 * Content type mappings
203
 */
204
interface ContentObject {
205
  [mediatype: string]: MediaTypeObject;
206
}
207

208
/**
209
 * Media type definition with schema and examples
210
 */
211
interface MediaTypeObject extends ISpecificationExtension {
212
  schema?: SchemaObject | ReferenceObject;
213
  examples?: ExamplesObject;
214
  example?: any;
215
  encoding?: EncodingObject;
216
}
217

218
/**
219
 * Response definitions container
220
 */
221
interface ResponsesObject extends ISpecificationExtension {
222
  default?: ResponseObject | ReferenceObject;
223
  [statuscode: string]: ResponseObject | ReferenceObject | any;
224
}
225

226
/**
227
 * HTTP response definition
228
 */
229
interface ResponseObject extends ISpecificationExtension {
230
  description: string;
231
  headers?: HeadersObject;
232
  content?: ContentObject;
233
  links?: LinksObject;
234
}
235

236
/**
237
 * Headers container
238
 */
239
interface HeadersObject {
240
  [name: string]: HeaderObject | ReferenceObject;
241
}
242

243
/**
244
 * Header definition (extends BaseParameterObject)
245
 */
246
interface HeaderObject extends BaseParameterObject {
247
  $ref?: string;
248
}
249
```
250

251
### Schema Interfaces  
252

253
JSON Schema interfaces for OpenAPI 3.0.
254

255
```typescript { .api }
256
/**
257
 * JSON Schema types for OpenAPI 3.0
258
 */
259
type SchemaObjectType =
260
  | 'integer'
261
  | 'number'
262
  | 'string'
263
  | 'boolean'
264
  | 'object'
265
  | 'null'
266
  | 'array';
267

268
/**
269
 * JSON Schema formats
270
 */
271
type SchemaObjectFormat =
272
  | 'int32'
273
  | 'int64'
274
  | 'float'
275
  | 'double'
276
  | 'byte'
277
  | 'binary'
278
  | 'date'
279
  | 'date-time'
280
  | 'password'
281
  | string;
282

283
/**
284
 * JSON Schema definition for OpenAPI 3.0
285
 */
286
interface SchemaObject extends ISpecificationExtension {
287
  nullable?: boolean;
288
  discriminator?: DiscriminatorObject;
289
  readOnly?: boolean;
290
  writeOnly?: boolean;
291
  xml?: XmlObject;
292
  externalDocs?: ExternalDocumentationObject;
293
  example?: any;
294
  examples?: any[];
295
  deprecated?: boolean;
296
  
297
  type?: SchemaObjectType | SchemaObjectType[];
298
  format?: SchemaObjectFormat;
299
  allOf?: (SchemaObject | ReferenceObject)[];
300
  oneOf?: (SchemaObject | ReferenceObject)[];
301
  anyOf?: (SchemaObject | ReferenceObject)[];
302
  not?: SchemaObject | ReferenceObject;
303
  items?: SchemaObject | ReferenceObject;
304
  properties?: { [propertyName: string]: SchemaObject | ReferenceObject };
305
  additionalProperties?: SchemaObject | ReferenceObject | boolean;
306
  description?: string;
307
  default?: any;
308
  
309
  title?: string;
310
  multipleOf?: number;
311
  maximum?: number;
312
  exclusiveMaximum?: boolean; // Boolean in OpenAPI 3.0
313
  minimum?: number;
314
  exclusiveMinimum?: boolean; // Boolean in OpenAPI 3.0
315
  maxLength?: number;
316
  minLength?: number;
317
  pattern?: string;
318
  maxItems?: number;
319
  minItems?: number;
320
  uniqueItems?: boolean;
321
  maxProperties?: number;
322
  minProperties?: number;
323
  required?: string[];
324
  enum?: any[];
325
}
326

327
/**
328
 * Schemas container
329
 */
330
interface SchemasObject {
331
  [schema: string]: SchemaObject;
332
}
333

334
/**
335
 * Polymorphism discriminator
336
 */
337
interface DiscriminatorObject {
338
  propertyName: string;
339
  mapping?: { [key: string]: string };
340
}
341

342
/**
343
 * XML serialization metadata
344
 */
345
interface XmlObject extends ISpecificationExtension {
346
  name?: string;
347
  namespace?: string;
348
  prefix?: string;
349
  attribute?: boolean;
350
  wrapped?: boolean;
351
}
352
```
353

354
### Reference Interface
355

356
Interface for referencing components.
357

358
```typescript { .api }
359
/**
360
 * Reference to another component
361
 */
362
interface ReferenceObject {
363
  $ref: string;
364
}
365
```
366

367
### Security Interfaces
368

369
Interfaces for API security definitions.
370

371
```typescript { .api }
372
/**
373
 * Security scheme types
374
 */
375
type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
376

377
/**
378
 * Security scheme definition
379
 */
380
interface SecuritySchemeObject extends ISpecificationExtension {
381
  type: SecuritySchemeType;
382
  description?: string;
383
  name?: string; // required only for apiKey
384
  in?: string; // required only for apiKey
385
  scheme?: string; // required only for http
386
  bearerFormat?: string;
387
  flows?: OAuthFlowsObject; // required only for oauth2
388
  openIdConnectUrl?: string; // required only for openIdConnect
389
}
390

391
/**
392
 * OAuth flows container
393
 */
394
interface OAuthFlowsObject extends ISpecificationExtension {
395
  implicit?: OAuthFlowObject;
396
  password?: OAuthFlowObject;
397
  clientCredentials?: OAuthFlowObject;
398
  authorizationCode?: OAuthFlowObject;
399
}
400

401
/**
402
 * OAuth flow definition
403
 */
404
interface OAuthFlowObject extends ISpecificationExtension {
405
  authorizationUrl?: string;
406
  tokenUrl?: string;
407
  refreshUrl?: string;
408
  scopes: ScopesObject;
409
}
410

411
/**
412
 * OAuth scopes definition
413
 */
414
interface ScopesObject extends ISpecificationExtension {
415
  [scope: string]: any;
416
}
417

418
/**
419
 * Security requirement
420
 */
421
interface SecurityRequirementObject {
422
  [name: string]: string[];
423
}
424
```
425

426
### Link and Callback Interfaces
427

428
Interfaces for response links and callbacks.
429

430
```typescript { .api }
431
/**
432
 * Links container
433
 */
434
interface LinksObject {
435
  [name: string]: LinkObject | ReferenceObject;
436
}
437

438
/**
439
 * Link definition for connecting operations
440
 */
441
interface LinkObject extends ISpecificationExtension {
442
  operationRef?: string;
443
  operationId?: string;
444
  parameters?: LinkParametersObject;
445
  requestBody?: any | string;
446
  description?: string;
447
  server?: ServerObject;
448
  [property: string]: any;
449
}
450

451
/**
452
 * Link parameters mapping
453
 */
454
interface LinkParametersObject {
455
  [name: string]: any | string;
456
}
457

458
/**
459
 * Callbacks container
460
 */
461
interface CallbacksObject extends ISpecificationExtension {
462
  [name: string]: CallbackObject | ReferenceObject | any;
463
}
464

465
/**
466
 * Callback definition for asynchronous operations
467
 */
468
interface CallbackObject extends ISpecificationExtension {
469
  [name: string]: PathItemObject | any;
470
}
471
```
472

473
### Example and Encoding Interfaces
474

475
Interfaces for examples and content encoding.
476

477
```typescript { .api }
478
/**
479
 * Examples container
480
 */
481
interface ExamplesObject {
482
  [name: string]: ExampleObject | ReferenceObject;
483
}
484

485
/**
486
 * Example value definition
487
 */
488
interface ExampleObject {
489
  summary?: string;
490
  description?: string;
491
  value?: any;
492
  externalValue?: string;
493
  [property: string]: any;
494
}
495

496
/**
497
 * Encoding definitions container
498
 */
499
interface EncodingObject extends ISpecificationExtension {
500
  [property: string]: EncodingPropertyObject | any;
501
}
502

503
/**
504
 * Individual encoding property
505
 */
506
interface EncodingPropertyObject {
507
  contentType?: string;
508
  headers?: { [key: string]: HeaderObject | ReferenceObject };
509
  style?: string;
510
  explode?: boolean;
511
  allowReserved?: boolean;
512
  [key: string]: any;
513
}
514
```
515

516
### Tag Interface
517

518
Interface for API tags.
519

520
```typescript { .api }
521
/**
522
 * Tag metadata for operations
523
 */
524
interface TagObject extends ISpecificationExtension {
525
  name: string;
526
  description?: string;
527
  externalDocs?: ExternalDocumentationObject;
528
  [extension: string]: any;
529
}
530
```
531

532
## Type Aliases and Enums
533

534
Additional type definitions for parameters, schemas, and security schemes.
535

536
```typescript { .api }
537
/**
538
 * Parameter location options
539
 * @deprecated - Use ParameterLocation type instead
540
 */
541
type PathObject = PathsObject;
542

543
/**
544
 * The location of a parameter
545
 * Possible values are "query", "header", "path" or "cookie"
546
 */
547
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
548

549
/**
550
 * The style of a parameter
551
 * Describes how the parameter value will be serialized
552
 */
553
type ParameterStyle =
554
    | 'matrix'
555
    | 'label'
556
    | 'form'
557
    | 'simple'
558
    | 'spaceDelimited'
559
    | 'pipeDelimited'
560
    | 'deepObject';
561

562
/**
563
 * Valid schema types
564
 */
565
type SchemaObjectType =
566
    | 'integer'
567
    | 'number'
568
    | 'string'
569
    | 'boolean'
570
    | 'object'
571
    | 'null'
572
    | 'array';
573

574
/**
575
 * Valid schema formats
576
 */
577
type SchemaObjectFormat =
578
    | 'int32'
579
    | 'int64'
580
    | 'float'
581
    | 'double'
582
    | 'byte'
583
    | 'binary'
584
    | 'date'
585
    | 'date-time'
586
    | 'password'
587
    | string;
588
```
589

590
## Utility Functions
591

592
Type guards and utility functions for working with OpenAPI types.
593

594
```typescript { .api }
595
/**
596
 * Extract path item from paths object, ignoring extensions
597
 * @param pathsObject - Paths container object
598
 * @param path - Path string to retrieve
599
 * @returns PathItemObject if found, undefined otherwise
600
 */
601
function getPath(pathsObject: PathsObject, path: string): PathItemObject | undefined;
602

603
/**
604
 * Type guard to check if object is a ReferenceObject
605
 * @param obj - Object to check
606
 * @returns True if object is a ReferenceObject
607
 */
608
function isReferenceObject(obj: any): obj is ReferenceObject;
609

610
/**
611
 * Type guard to check if schema is a SchemaObject (not a ReferenceObject)
612
 * @param schema - Schema to check
613
 * @returns True if schema is a SchemaObject
614
 */
615
function isSchemaObject(schema: SchemaObject | ReferenceObject): schema is SchemaObject;
616
```
617

618
## Usage Examples
619

620
### Complete Type Usage
621

622
```typescript
623
import { oas30 } from "openapi3-ts";
624
import { getPath, isReferenceObject, isSchemaObject } from "openapi3-ts/oas30";
625

626
// Create typed OpenAPI document
627
const openApiDoc: oas30.OpenAPIObject = {
628
  openapi: "3.0.3",
629
  info: {
630
    title: "Typed API",
631
    version: "1.0.0"
632
  },
633
  paths: {
634
    "/users": {
635
      get: {
636
        summary: "Get users",
637
        responses: {
638
          "200": {
639
            description: "Success",
640
            content: {
641
              "application/json": {
642
                schema: {
643
                  type: "array",
644
                  items: { $ref: "#/components/schemas/User" }
645
                }
646
              }
647
            }
648
          }
649
        }
650
      }
651
    }
652
  },
653
  components: {
654
    schemas: {
655
      User: {
656
        type: "object",
657
        required: ["id", "name"],
658
        properties: {
659
          id: { type: "integer", format: "int64" },
660
          name: { type: "string" },
661
          email: { type: "string", format: "email" }
662
        }
663
      }
664
    }
665
  }
666
};
667

668
// Type-safe access with utility functions
669
const userPath = getPath(openApiDoc.paths, "/users");
670
if (userPath && userPath.get) {
671
  console.log(userPath.get.summary); // "Get users"
672
}
673

674
// Type guards
675
const userSchema = openApiDoc.components?.schemas?.User;
676
if (userSchema && isSchemaObject(userSchema)) {
677
  console.log(userSchema.type); // "object"
678
  console.log(userSchema.required); // ["id", "name"]
679
}
680
```