0
# OpenAPI 3.1 Types
1

2
Enhanced TypeScript interfaces for OpenAPI 3.1 with JSON Schema Draft 2020-12 support and webhook definitions.
3

4
## Capabilities
5

6
### Core Document Interfaces
7

8
Enhanced document structure with OpenAPI 3.1 features.
9

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

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

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

47
/**
48
 * License information with optional identifier (enhanced in 3.1)
49
 */
50
interface LicenseObject extends ISpecificationExtension {
51
  name: string;
52
  identifier?: string; // New in OpenAPI 3.1
53
  url?: string;
54
}
55
```
56

57
### Enhanced Component Container
58

59
Component container with path items support.
60

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

79
### Path and Operation Interfaces
80

81
Same as OpenAPI 3.0 with optional paths support.
82

83
```typescript { .api }
84
/**
85
 * Container for API paths (optional in OpenAPI 3.1)
86
 */
87
interface PathsObject extends ISpecificationExtension {
88
  [path: string]: PathItemObject;
89
}
90

91
/**
92
 * @deprecated Use PathsObject instead
93
 */
94
type PathObject = PathsObject;
95

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

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

133
/**
134
 * External documentation reference (same as 3.0)
135
 */
136
interface ExternalDocumentationObject extends ISpecificationExtension {
137
  description?: string;
138
  url: string;
139
}
140
```
141

142
### Parameter Interfaces
143

144
Same parameter interfaces as OpenAPI 3.0.
145

146
```typescript { .api }
147
/**
148
 * Parameter location type
149
 */
150
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
151

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

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

181
/**
182
 * Complete parameter definition (same as 3.0)
183
 */
184
interface ParameterObject extends BaseParameterObject {
185
  name: string;
186
  in: ParameterLocation;
187
}
188
```
189

190
### Request and Response Interfaces
191

192
Same interfaces as OpenAPI 3.0.
193

194
```typescript { .api }
195
/**
196
 * Request body definition (same as 3.0)
197
 */
198
interface RequestBodyObject extends ISpecificationExtension {
199
  description?: string;
200
  content: ContentObject;
201
  required?: boolean;
202
}
203

204
/**
205
 * Content type mappings (same as 3.0)
206
 */
207
interface ContentObject {
208
  [mediatype: string]: MediaTypeObject;
209
}
210

211
/**
212
 * Media type definition (same as 3.0)
213
 */
214
interface MediaTypeObject extends ISpecificationExtension {
215
  schema?: SchemaObject | ReferenceObject;
216
  examples?: ExamplesObject;
217
  example?: any;
218
  encoding?: EncodingObject;
219
}
220

221
/**
222
 * Response definitions container (same as 3.0)
223
 */
224
interface ResponsesObject extends ISpecificationExtension {
225
  default?: ResponseObject | ReferenceObject;
226
  [statuscode: string]: ResponseObject | ReferenceObject | any;
227
}
228

229
/**
230
 * HTTP response definition (same as 3.0)
231
 */
232
interface ResponseObject extends ISpecificationExtension {
233
  description: string;
234
  headers?: HeadersObject;
235
  content?: ContentObject;
236
  links?: LinksObject;
237
}
238

239
/**
240
 * Headers container (same as 3.0)
241
 */
242
interface HeadersObject {
243
  [name: string]: HeaderObject | ReferenceObject;
244
}
245

246
/**
247
 * Header definition (same as 3.0)
248
 */
249
interface HeaderObject extends BaseParameterObject {
250
  $ref?: string;
251
}
252
```
253

254
### Enhanced Schema Interface
255

256
JSON Schema Draft 2020-12 compliant schema with OpenAPI 3.1 enhancements.
257

258
```typescript { .api }
259
/**
260
 * JSON Schema types (same as 3.0)
261
 */
262
type SchemaObjectType =
263
  | 'integer'
264
  | 'number'
265
  | 'string'
266
  | 'boolean'
267
  | 'object'
268
  | 'null'
269
  | 'array';
270

271
/**
272
 * Enhanced JSON Schema definition for OpenAPI 3.1
273
 */
274
interface SchemaObject extends ISpecificationExtension {
275
  $ref?: string; // Reference support in schemas
276
  discriminator?: DiscriminatorObject;
277
  readOnly?: boolean;
278
  writeOnly?: boolean;
279
  xml?: XmlObject;
280
  externalDocs?: ExternalDocumentationObject;
281
  example?: any; // @deprecated use examples instead
282
  examples?: any[];
283
  deprecated?: boolean;
284
  
285
  type?: SchemaObjectType | SchemaObjectType[];
286
  format?:
287
    | 'int32'
288
    | 'int64'
289
    | 'float'
290
    | 'double'
291
    | 'byte'
292
    | 'binary'
293
    | 'date'
294
    | 'date-time'
295
    | 'password'
296
    | string;
297
  allOf?: (SchemaObject | ReferenceObject)[];
298
  oneOf?: (SchemaObject | ReferenceObject)[];
299
  anyOf?: (SchemaObject | ReferenceObject)[];
300
  not?: SchemaObject | ReferenceObject;
301
  items?: SchemaObject | ReferenceObject;
302
  properties?: { [propertyName: string]: SchemaObject | ReferenceObject };
303
  additionalProperties?: SchemaObject | ReferenceObject | boolean;
304
  propertyNames?: SchemaObject | ReferenceObject; // New in OpenAPI 3.1
305
  description?: string;
306
  default?: any;
307
  
308
  title?: string;
309
  multipleOf?: number;
310
  maximum?: number;
311
  const?: any; // New in OpenAPI 3.1
312
  exclusiveMaximum?: number; // Changed to number in OpenAPI 3.1
313
  minimum?: number;
314
  exclusiveMinimum?: number; // Changed to number in OpenAPI 3.1
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
  prefixItems?: (SchemaObject | ReferenceObject)[]; // New in OpenAPI 3.1
326
  contentMediaType?: string; // New in OpenAPI 3.1
327
  contentEncoding?: string; // New in OpenAPI 3.1
328
}
329

330
/**
331
 * Schemas container (same as 3.0)
332
 */
333
interface SchemasObject {
334
  [schema: string]: SchemaObject;
335
}
336

337
/**
338
 * Polymorphism discriminator (same as 3.0)
339
 */
340
interface DiscriminatorObject {
341
  propertyName: string;
342
  mapping?: { [key: string]: string };
343
}
344

345
/**
346
 * XML serialization metadata (same as 3.0)
347
 */
348
interface XmlObject extends ISpecificationExtension {
349
  name?: string;
350
  namespace?: string;
351
  prefix?: string;
352
  attribute?: boolean;
353
  wrapped?: boolean;
354
}
355
```
356

357
### Enhanced Reference Interface
358

359
Reference objects with summary and description support.
360

361
```typescript { .api }
362
/**
363
 * Enhanced reference object with summary and description
364
 */
365
interface ReferenceObject {
366
  $ref: string;
367
  summary?: string; // New in OpenAPI 3.1
368
  description?: string; // New in OpenAPI 3.1
369
}
370
```
371

372
### Security Interfaces
373

374
Same security interfaces as OpenAPI 3.0.
375

376
```typescript { .api }
377
/**
378
 * Security scheme types (same as 3.0)
379
 */
380
type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
381

382
/**
383
 * Security scheme definition (same as 3.0)
384
 */
385
interface SecuritySchemeObject extends ISpecificationExtension {
386
  type: SecuritySchemeType;
387
  description?: string;
388
  name?: string; // required only for apiKey
389
  in?: string; // required only for apiKey
390
  scheme?: string; // required only for http
391
  bearerFormat?: string;
392
  flows?: OAuthFlowsObject; // required only for oauth2
393
  openIdConnectUrl?: string; // required only for openIdConnect
394
}
395

396
/**
397
 * OAuth flows container (same as 3.0)
398
 */
399
interface OAuthFlowsObject extends ISpecificationExtension {
400
  implicit?: OAuthFlowObject;
401
  password?: OAuthFlowObject;
402
  clientCredentials?: OAuthFlowObject;
403
  authorizationCode?: OAuthFlowObject;
404
}
405

406
/**
407
 * OAuth flow definition (same as 3.0)
408
 */
409
interface OAuthFlowObject extends ISpecificationExtension {
410
  authorizationUrl?: string;
411
  tokenUrl?: string;
412
  refreshUrl?: string;
413
  scopes: ScopesObject;
414
}
415

416
/**
417
 * OAuth scopes definition (same as 3.0)
418
 */
419
interface ScopesObject extends ISpecificationExtension {
420
  [scope: string]: any;
421
}
422

423
/**
424
 * Security requirement (same as 3.0)
425
 */
426
interface SecurityRequirementObject {
427
  [name: string]: string[];
428
}
429
```
430

431
### Link and Callback Interfaces
432

433
Same interfaces as OpenAPI 3.0.
434

435
```typescript { .api }
436
/**
437
 * Links container (same as 3.0)
438
 */
439
interface LinksObject {
440
  [name: string]: LinkObject | ReferenceObject;
441
}
442

443
/**
444
 * Link definition (same as 3.0)
445
 */
446
interface LinkObject extends ISpecificationExtension {
447
  operationRef?: string;
448
  operationId?: string;
449
  parameters?: LinkParametersObject;
450
  requestBody?: any | string;
451
  description?: string;
452
  server?: ServerObject;
453
  [property: string]: any;
454
}
455

456
/**
457
 * Link parameters mapping (same as 3.0)
458
 */
459
interface LinkParametersObject {
460
  [name: string]: any | string;
461
}
462

463
/**
464
 * Callbacks container (same as 3.0)
465
 */
466
interface CallbacksObject extends ISpecificationExtension {
467
  [name: string]: CallbackObject | ReferenceObject | any;
468
}
469

470
/**
471
 * Callback definition (same as 3.0)
472
 */
473
interface CallbackObject extends ISpecificationExtension {
474
  [name: string]: PathItemObject | any;
475
}
476
```
477

478
### Example and Encoding Interfaces
479

480
Same interfaces as OpenAPI 3.0.
481

482
```typescript { .api }
483
/**
484
 * Examples container (same as 3.0)
485
 */
486
interface ExamplesObject {
487
  [name: string]: ExampleObject | ReferenceObject;
488
}
489

490
/**
491
 * Example value definition (same as 3.0)
492
 */
493
interface ExampleObject {
494
  summary?: string;
495
  description?: string;
496
  value?: any;
497
  externalValue?: string;
498
  [property: string]: any;
499
}
500

501
/**
502
 * Encoding definitions container (same as 3.0)
503
 */
504
interface EncodingObject extends ISpecificationExtension {
505
  [property: string]: EncodingPropertyObject | any;
506
}
507

508
/**
509
 * Individual encoding property (same as 3.0)
510
 */
511
interface EncodingPropertyObject {
512
  contentType?: string;
513
  headers?: { [key: string]: HeaderObject | ReferenceObject };
514
  style?: string;
515
  explode?: boolean;
516
  allowReserved?: boolean;
517
  [key: string]: any;
518
}
519
```
520

521
### Tag Interface
522

523
Same as OpenAPI 3.0.
524

525
```typescript { .api }
526
/**
527
 * Tag metadata (same as 3.0)
528
 */
529
interface TagObject extends ISpecificationExtension {
530
  name: string;
531
  description?: string;
532
  externalDocs?: ExternalDocumentationObject;
533
  [extension: string]: any;
534
}
535
```
536

537
## Type Aliases and Enums
538

539
Additional type definitions for parameters, schemas, and security schemes in OpenAPI 3.1.
540

541
```typescript { .api }
542
/**
543
 * Parameter location options
544
 * @deprecated - Use ParameterLocation type instead
545
 */
546
type PathObject = PathsObject;
547

548
/**
549
 * The location of a parameter
550
 * Possible values are "query", "header", "path" or "cookie"
551
 */
552
type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
553

554
/**
555
 * The style of a parameter
556
 * Describes how the parameter value will be serialized
557
 */
558
type ParameterStyle =
559
    | 'matrix'
560
    | 'label'
561
    | 'form'
562
    | 'simple'
563
    | 'spaceDelimited'
564
    | 'pipeDelimited'
565
    | 'deepObject';
566

567
/**
568
 * Valid schema types in OpenAPI 3.1
569
 */
570
type SchemaObjectType =
571
    | 'integer'
572
    | 'number'
573
    | 'string'
574
    | 'boolean'
575
    | 'object'
576
    | 'null'
577
    | 'array';
578

579
/**
580
 * Valid security scheme types in OpenAPI 3.1
581
 */
582
type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
583
```
584

585
## Utility Functions
586

587
Enhanced utility functions for OpenAPI 3.1.
588

589
```typescript { .api }
590
/**
591
 * Extract path item from paths object, handling optional paths
592
 * @param pathsObject - Paths container object (can be undefined in 3.1)
593
 * @param path - Path string to retrieve
594
 * @returns PathItemObject if found, undefined otherwise
595
 */
596
function getPath(
597
  pathsObject: PathsObject | undefined,
598
  path: string
599
): PathItemObject | undefined;
600

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

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

616
## OpenAPI 3.1 Enhanced Features
617

618
### Enhanced Schema Examples
619

620
```typescript
621
import { oas31 } from "openapi3-ts";
622
import { getPath, isReferenceObject, isSchemaObject } from "openapi3-ts/oas31";
623

624
// JSON Schema Draft 2020-12 features
625
const enhancedUserSchema: oas31.SchemaObject = {
626
  type: "object",
627
  required: ["id", "name"],
628
  properties: {
629
    id: { 
630
      type: "integer",
631
      minimum: 1,
632
      exclusiveMinimum: 0 // Numeric in 3.1 (vs boolean in 3.0)
633
    },
634
    name: { type: "string" },
635
    role: {
636
      const: "user" // Constant value constraint
637
    },
638
    preferences: {
639
      type: "array",
640
      prefixItems: [ // Tuple validation
641
        { type: "string" }, // First item must be string
642
        { type: "boolean" } // Second item must be boolean
643
      ],
644
      items: false // No additional items allowed
645
    },
646
    metadata: {
647
      type: "string",
648
      contentMediaType: "application/json", // Content type hint
649
      contentEncoding: "base64" // Encoding hint
650
    }
651
  },
652
  propertyNames: { // Property name validation
653
    pattern: "^[a-zA-Z_][a-zA-Z0-9_]*$"
654
  }
655
};
656

657
// Enhanced reference with summary and description
658
const userReference: oas31.ReferenceObject = {
659
  $ref: "#/components/schemas/User",
660
  summary: "User model reference",
661
  description: "Standard user object with all required fields"
662
};
663

664
// License with identifier
665
const mitLicense: oas31.LicenseObject = {
666
  name: "MIT",
667
  identifier: "MIT", // SPDX license identifier
668
  url: "https://opensource.org/licenses/MIT"
669
};
670
```
671

672
### Webhook Usage Example
673

674
```typescript
675
const openApiDoc: oas31.OpenAPIObject = {
676
  openapi: "3.1.0",
677
  info: {
678
    title: "Enhanced API",
679
    version: "1.0.0"
680
  },
681
  paths: {
682
    "/users": {
683
      get: {
684
        responses: {
685
          "200": {
686
            description: "Success"
687
          }
688
        }
689
      }
690
    }
691
  },
692
  webhooks: {
693
    userCreated: {
694
      post: {
695
        summary: "User created webhook",
696
        requestBody: {
697
          content: {
698
            "application/json": {
699
              schema: { $ref: "#/components/schemas/User" }
700
            }
701
          }
702
        },
703
        responses: {
704
          "200": {
705
            description: "Webhook processed"
706
          }
707
        }
708
      }
709
    }
710
  },
711
  components: {
712
    schemas: {
713
      User: enhancedUserSchema
714
    }
715
  }
716
};
717
```