0
# OpenAPI 3.1 Types
1

2
Complete type definitions for the OpenAPI 3.1 specification with support for JSON Schema 2020-12, webhooks, enhanced reference objects, and additional schema features.
3

4
## Capabilities
5

6
### Document Structure
7

8
Core document type representing the root OpenAPI 3.1 specification document.
9

10
```typescript { .api }
11
/**
12
 * Root OpenAPI 3.1 document structure
13
 * @template T - Extension object type for custom properties
14
 */
15
type Document<T extends {} = {}> = {
16
  openapi: string;
17
  info: InfoObject;
18
  jsonSchemaDialect?: string;
19
  servers?: ServerObject[];
20
} & (
21
  | { paths: PathsObject<T>; webhooks?: Record<string, PathItemObject | ReferenceObject>; components?: ComponentsObject; }
22
  | { webhooks: Record<string, PathItemObject | ReferenceObject>; paths?: PathsObject<T>; components?: ComponentsObject; }
23
  | { components: ComponentsObject; paths?: PathsObject<T>; webhooks?: Record<string, PathItemObject | ReferenceObject>; }
24
);
25
```
26

27
### Info and Metadata
28

29
API metadata and information objects with OpenAPI 3.1 enhancements.
30

31
```typescript { .api }
32
/**
33
 * Enhanced API information object for OpenAPI 3.1 
34
 */
35
type InfoObject = {
36
  title: string;
37
  summary?: string;
38
  description?: string;
39
  termsOfService?: string;
40
  contact?: ContactObject;
41
  license?: LicenseObject;
42
  version: string;
43
};
44

45
/**
46
 * Contact information object
47
 */
48
type ContactObject = {
49
  name?: string;
50
  url?: string;
51
  email?: string;
52
};
53

54
/**
55
 * License information object with identifier support
56
 */
57
type LicenseObject = {
58
  name: string;
59
  identifier?: string;
60
  url?: string;
61
};
62
```
63

64
### Server Configuration
65

66
Server and server variable definitions for OpenAPI 3.1.
67

68
```typescript { .api }
69
/**
70
 * Server configuration object
71
 */
72
type ServerObject = {
73
  url: string;
74
  description?: string;
75
  variables?: Record<string, ServerVariableObject>;
76
};
77

78
/**
79
 * Server variable object with enhanced enum support
80
 */
81
type ServerVariableObject = {
82
  enum?: [string, ...string[]];
83
  default: string;
84
  description?: string;
85
};
86
```
87

88
### Path and Operation Objects
89

90
Path definitions and HTTP operations with OpenAPI 3.1 enhancements.
91

92
```typescript { .api }
93
/**
94
 * Collection of API paths
95
 * @template T - Extension object type for custom properties
96
 * @template P - Path-level extension object type
97
 */
98
type PathsObject<T extends {} = {}, P extends {} = {}> = Record<
99
  string,
100
  (PathItemObject<T> & P) | undefined
101
>;
102

103
/**
104
 * Path item object with operation definitions
105
 * @template T - Extension object type for custom properties
106
 */
107
type PathItemObject<T extends {} = {}> = {
108
  $ref?: string;
109
  summary?: string;
110
  description?: string;
111
  servers?: ServerObject[];
112
  parameters?: (ReferenceObject | ParameterObject)[];
113
  get?: OperationObject<T>;
114
  put?: OperationObject<T>;
115
  post?: OperationObject<T>;
116
  delete?: OperationObject<T>;
117
  options?: OperationObject<T>;
118
  head?: OperationObject<T>;
119
  patch?: OperationObject<T>;
120
  trace?: OperationObject<T>;
121
};
122

123
/**
124
 * HTTP operation object
125
 * @template T - Extension object type for custom properties
126
 */
127
type OperationObject<T extends {} = {}> = {
128
  tags?: string[];
129
  summary?: string;
130
  description?: string;
131
  externalDocs?: ExternalDocumentationObject;
132
  operationId?: string;
133
  parameters?: (ReferenceObject | ParameterObject)[];
134
  requestBody?: ReferenceObject | RequestBodyObject;
135
  responses?: ResponsesObject;
136
  callbacks?: Record<string, ReferenceObject | CallbackObject>;
137
  deprecated?: boolean;
138
  security?: SecurityRequirementObject[];
139
  servers?: ServerObject[];
140
} & T;
141
```
142

143
### Schema System
144

145
Enhanced schema objects supporting JSON Schema 2020-12 features.
146

147
```typescript { .api }
148
/**
149
 * Enhanced schema object supporting mixed types and JSON Schema 2020-12 features
150
 */
151
type SchemaObject = ArraySchemaObject | NonArraySchemaObject | MixedSchemaObject;
152

153
/**
154
 * Array schema object
155
 */
156
interface ArraySchemaObject extends BaseSchemaObject {
157
  type: 'array';
158
  items: ReferenceObject | SchemaObject;
159
}
160

161
/**
162
 * Non-array schema object with null support
163
 */
164
interface NonArraySchemaObject extends BaseSchemaObject {
165
  type?: 'boolean' | 'object' | 'number' | 'string' | 'integer' | 'null';
166
}
167

168
/**
169
 * Mixed schema object supporting multiple types
170
 */
171
interface MixedSchemaObject extends BaseSchemaObject {
172
  type?: ('array' | 'boolean' | 'object' | 'number' | 'string' | 'integer' | 'null')[];
173
  items?: ReferenceObject | SchemaObject;
174
}
175

176
/**
177
 * Base schema object with JSON Schema 2020-12 features
178
 */
179
type BaseSchemaObject = {
180
  title?: string;
181
  description?: string;
182
  format?: string;
183
  default?: any;
184
  multipleOf?: number;
185
  maximum?: number;
186
  exclusiveMaximum?: boolean | number;
187
  minimum?: number;
188
  exclusiveMinimum?: boolean | number;
189
  maxLength?: number;
190
  minLength?: number;
191
  pattern?: string;
192
  maxItems?: number;
193
  minItems?: number;
194
  uniqueItems?: boolean;
195
  maxProperties?: number;
196
  minProperties?: number;
197
  required?: string[];
198
  enum?: any[];
199
  const?: any;
200
  examples?: any[];
201
  contentMediaType?: string;
202
  $schema?: string;
203
  additionalProperties?: boolean | ReferenceObject | SchemaObject;
204
  properties?: { [name: string]: ReferenceObject | SchemaObject };
205
  allOf?: (ReferenceObject | SchemaObject)[];
206
  oneOf?: (ReferenceObject | SchemaObject)[];
207
  anyOf?: (ReferenceObject | SchemaObject)[];
208
  not?: ReferenceObject | SchemaObject;
209
  discriminator?: DiscriminatorObject;
210
  readOnly?: boolean;
211
  writeOnly?: boolean;
212
  xml?: XMLObject;
213
  externalDocs?: ExternalDocumentationObject;
214
  example?: any;
215
  deprecated?: boolean;
216
};
217
```
218

219
### Reference Objects
220

221
Enhanced reference objects with summary and description support.
222

223
```typescript { .api }
224
/**
225
 * Enhanced reference object with summary and description
226
 */
227
type ReferenceObject = {
228
  $ref: string;
229
  summary?: string;
230
  description?: string;
231
};
232
```
233

234
### Request and Response Objects
235

236
Request body and response definitions for OpenAPI 3.1.
237

238
```typescript { .api }
239
/**
240
 * Request body object
241
 */
242
type RequestBodyObject = {
243
  description?: string;
244
  content: { [media: string]: MediaTypeObject };
245
  required?: boolean;
246
};
247

248
/**
249
 * Collection of response objects
250
 */
251
type ResponsesObject = Record<string, ReferenceObject | ResponseObject>;
252

253
/**
254
 * Response object definition
255
 */
256
type ResponseObject = {
257
  description: string;
258
  headers?: { [header: string]: ReferenceObject | HeaderObject };
259
  content?: { [media: string]: MediaTypeObject };
260
  links?: { [link: string]: ReferenceObject | LinkObject };
261
};
262

263
/**
264
 * Media type object with schema and examples
265
 */
266
type MediaTypeObject = {
267
  schema?: SchemaObject | ReferenceObject;
268
  example?: any;
269
  examples?: Record<string, ReferenceObject | ExampleObject>;
270
  encoding?: { [media: string]: EncodingObject };
271
};
272
```
273

274
### Components Object
275

276
Reusable components collection for OpenAPI 3.1.
277

278
```typescript { .api }
279
/**
280
 * Reusable components object
281
 */
282
type ComponentsObject = {
283
  schemas?: Record<string, SchemaObject>;
284
  responses?: Record<string, ReferenceObject | ResponseObject>;
285
  parameters?: Record<string, ReferenceObject | ParameterObject>;
286
  examples?: Record<string, ReferenceObject | ExampleObject>;
287
  requestBodies?: Record<string, ReferenceObject | RequestBodyObject>;
288
  headers?: Record<string, ReferenceObject | HeaderObject>;
289
  securitySchemes?: Record<string, ReferenceObject | SecuritySchemeObject>;
290
  links?: Record<string, ReferenceObject | LinkObject>;
291
  callbacks?: Record<string, ReferenceObject | CallbackObject>;
292
  pathItems?: Record<string, ReferenceObject | PathItemObject>;
293
};
294
```
295

296
**Usage Examples:**
297

298
```typescript
299
import { OpenAPIV3_1 } from "openapi-types";
300

301
// OpenAPI 3.1 document with webhooks
302
const apiDoc: OpenAPIV3_1.Document = {
303
  openapi: "3.1.0",
304
  info: {
305
    title: "Webhook API",
306
    version: "1.0.0",
307
    summary: "API with webhook support"
308
  },
309
  jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema",
310
  webhooks: {
311
    newUser: {
312
      post: {
313
        requestBody: {
314
          content: {
315
            "application/json": {
316
              schema: {
317
                type: "object",
318
                properties: {
319
                  userId: { type: "string" },
320
                  email: { type: "string" }
321
                }
322
              }
323
            }
324
          }
325
        },
326
        responses: {
327
          "200": {
328
            description: "Webhook received"
329
          }
330
        }
331
      }
332
    }
333
  }
334
};
335

336
// Using enhanced schema features
337
const enhancedSchema: OpenAPIV3_1.SchemaObject = {
338
  type: ["string", "null"],
339
  examples: ["example1", "example2", null],
340
  const: "constant_value"
341
};
342

343
// Enhanced reference with description
344
const enhancedRef: OpenAPIV3_1.ReferenceObject = {
345
  $ref: "#/components/schemas/User",
346
  summary: "User reference",
347
  description: "Reference to the User schema"
348
};
349
```