Saving progress on types packages

.cursor/rules/filenames.mdc

@@ -0,0 +1,33 @@
+---
+description: File organization and Filename standards
+globs:
+alwaysApply: true
+---
+
+Please prefer simpler filenames
+
+For example, prefer string.ts over string-schema.ts
+
+All the top level keys for OpenAPI should have their own file, except for the OpenAPI key, which should be included in the root level specification file directly
+
+below is an example for OpenAPI format, but the same principles apply to Swagger 2.0
+The files for each spec should be as follows:
+- Info | info.ts
+- Servers | servers.ts
+- Paths | paths.ts
+- Components | components.ts
+- Security | security.ts
+- Tags | tags.ts
+
+Additional files should be created for the sub keys that require more detail:
+- ExternalDocs | externalDocs.ts not external-documentation.ts
+- Extensions | extensions.ts
+- References | references.ts
+- Callbacks | callbacks.ts
+- Webhooks | webhooks.ts
+- Parameters | parameters.ts
+- RequestBodies | requestBodies.ts
+- Responses | responses.ts
+- XML | xml.ts
+
+This philosophy should be applied to similar ideas and formats, and you should prioritize accurate, consistent, clean, descriptive, and detailed names, descriptions, patterns, and organization.

.cursor/rules/jsdoc-formatting.mdc

@@ -0,0 +1,114 @@
+---
+description: JSDoc formatting
+alwaysApply: true
+---
+
+All TypeScript types should be documented with JSDoc. With a similar level of detail as the example below and in a similar format.
+Ensure that the JSDoc comments contain links to the official OpenAPI specification version they represent, and to the correct section.
+
+Always prefer links to the official OpenAPI docs like https://spec.openapis.org/oas/v3.1.1.html over others.
+
+The JSDoc comments should be formatted as follows:
+- A title header for the type
+- A description of the type
+- A fields section laying out the fields of the type
+- A note section separating the fields and examples sections
+- An examples section providing thorough examples of the type, including the different variations of the type, especially if there are discriminated examples
+- property level comments for each field of the type that inlcude example values, with more detailed comments for the properties that are more complex.
+
+Ensure you Always:
+- use the `@key` tag to document the fields of the type.
+- use the `@see` tag to link to the official OpenAPI specification version they represent, and to the correct section.
+- use the `@example` tag to provide an example of the type.
+- use the `@note` tag to provide a note about the type.
+- use section headers ` * -----------------------------------------------------------------------------` to organize the JSDoc comments.
+
+The example below is for the Contact Object:
+
+/**
+ * -----------------------------------------------------------------------------
+ * Contact Object
+ * -----------------------------------------------------------------------------
+ *
+ * The Contact Object provides contact information for the exposed API.  
+ * It appears in the OpenAPI and Swagger specifications from v2.0 through v3.1.x.
+ *
+ * Specification Extensions (`x-*`) are always allowed.
+ *
+ *
+ * | Version | Reference |
+ * |---------|-----------|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#contact-object | OpenAPI 3.1.1 Contact} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#contact-object | OpenAPI 3.1.0 Contact} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact} |
+ * | 2.0     | {@link https://spec.openapis.org/oas/v2.0#contact-object   | Swagger 2.0 Contact}   |
+ *
+ * -----------------------------------------------------------------------------
+ * Fields
+ * -----------------------------------------------------------------------------
+ *
+ *
+ * @key `name` - Optional The identifying name of the contact person/organization.
+ * @key `url` - Optional A URL pointing to the contact information.
+ * @key `email` - Optional The email address of the contact person/organization.
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All fields are optional.
+ *
+ * -----------------------------------------------------------------------------
+ * Examples
+ * -----------------------------------------------------------------------------
+ *
+ * @example (full contact object):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "API Support",
+ *   url: "http://www.acme.com/support",
+ *   email: "support@acme.com"
+ * };
+ * ```
+ *
+ * @example (just name + email):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "Jane Doe",
+ *   email: "jane.doe@acme.com"
+ * };
+ * ```
+ *
+ * @example (with extension):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "Internal API Team",
+ *   email: "api-team@acme.com",
+ *   "x-slack": "#api-support"
+ * };
+ * ```
+ */
+export type Contact = {
+  /**
+   * The identifying name of the contact person/organization.
+   */
+  name?: string;
+
+  /**
+   * The URL pointing to the contact information.  
+   * MUST be in the format of a URL.
+   *
+   * Example: `"http://www.acme.com/support"`
+   */
+  url?: string;
+
+  /**
+   * The email address of the contact person/organization.  
+   * MUST be in the format of an email address.
+   *
+   * Example: `"support@acme.com"`
+   */
+  email?: string;
+}

.cursor/rules/non-atomic-design.mdc

@@ -0,0 +1,8 @@
+---
+description: Non-atomic design
+alwaysApply: true
+---
+
+When designing types, avoid using atomic types. Through the process of investigating the type signatures for OpenAPI I determind that some types are too different to encompass with a common base, and results in a much more complex type signature.
+
+The goal is for the types to be as easily consumable as possible, and be extremely detailed and specific to the OpenAPI specification version they represent.

.gitignore

@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store

MIGRATION.md

@@ -0,0 +1,102 @@
+# Migration Guide
+
+## Breaking Changes
+
+This version removes backward compatibility with legacy import paths. Please update your imports to use the new clean paths.
+
+## Import Path Changes
+
+### Before (Legacy - Removed)
+```typescript
+// ❌ These import paths are no longer supported
+import { SchemaObject } from 'oas-types/OpenAPI-3.1.0';
+import { SchemaObject30 } from 'oas-types/OpenAPI-3.0.0';
+import { SwaggerObject } from 'oas-types/Swagger-2.0';
+```
+
+### After (New Clean Paths)
+```typescript
+// ✅ Use these clean import paths
+import { SchemaObject } from 'oas-types/3.1.0';
+import { SchemaObject30 } from 'oas-types/3.0.0';
+import { SwaggerObject } from 'oas-types/2.0';
+```
+
+## Complete Import Reference
+
+### Atomic Types
+```typescript
+import { 
+  ContactObject, 
+  LicenseObject, 
+  InfoObject, 
+  ExternalDocumentationObject,
+  TagObject,
+  ReferenceObject,
+  ServerObject,
+  ServerVariableObject
+} from 'oas-types/atoms';
+```
+
+### Utilities
+```typescript
+import { 
+  DeepPartial, 
+  DeepRequired, 
+  Merge, 
+  Brand,
+  Versioned
+} from 'oas-types/utils';
+```
+
+### Common Types
+```typescript
+import { 
+  HttpMethod,
+  HttpStatusCode,
+  MimeType,
+  JsonSchemaFormat
+} from 'oas-types/common';
+```
+
+### Version-Specific Types
+```typescript
+// Swagger 2.0
+import { SwaggerObject } from 'oas-types/2.0';
+
+// OpenAPI 3.0.x
+import { SchemaObject30 } from 'oas-types/3.0.0';
+import { SchemaObject30 } from 'oas-types/3.0.1';
+import { SchemaObject30 } from 'oas-types/3.0.2';
+import { SchemaObject30 } from 'oas-types/3.0.3';
+import { SchemaObject30 } from 'oas-types/3.0.4';
+
+// OpenAPI 3.1.x
+import { SchemaObject } from 'oas-types/3.1.0';
+import { SchemaObject } from 'oas-types/3.1.1';
+```
+
+## Benefits of New Import Paths
+
+1. **Cleaner and shorter** - `oas-types/3.1.0` vs `oas-types/OpenAPI-3.1.0`
+2. **Consistent naming** - All versions follow the same pattern
+3. **Better IDE support** - Easier autocomplete and suggestions
+4. **Future-proof** - Easy to add new versions following the same pattern
+5. **Reduced bundle size** - No legacy exports to maintain
+
+## Migration Steps
+
+1. Update all import statements to use the new paths
+2. Remove any references to legacy import paths
+3. Test your application to ensure everything works correctly
+4. Update any documentation or examples in your codebase
+
+## Need Help?
+
+If you encounter any issues during migration, please:
+1. Check this migration guide
+2. Review the examples in `/examples/` directory
+3. Open an issue on GitHub with your specific use case
+
+
+

README.md

@@ -0,0 +1,243 @@
+# OpenAPI Types
+
+Comprehensive TypeScript definitions for all OpenAPI specification versions with a layered, version-aware architecture.
+
+## 🏗️ Architecture
+
+This library follows a **layered, version-aware types library** approach where:
+
+- **`atoms/`** - Contains canonical atomic types (common building blocks across OpenAPI versions)
+- **`3.0.0/`, `3.1.0/`, etc.** - Version-specific folders that extend/adapt atomic types
+- **`utils/`** - Shared helper types and utilities
+- **`common.ts`** - Common types and enums used across versions
+
+## 📦 Installation
+
+```bash
+npm install oas-types
+# or
+yarn add oas-types
+# or
+bun add oas-types
+```
+
+## 🚀 Usage
+
+### Import Atomic Types
+
+```typescript
+import { 
+  ContactObject, 
+  LicenseObject, 
+  InfoObject, 
+  ExternalDocumentationObject,
+  TagObject,
+  ReferenceObject,
+  ServerObject,
+  ServerVariableObject
+} from 'oas-types/atoms';
+```
+
+### Import Version-Specific Types
+
+```typescript
+// OpenAPI 3.0.0
+import { SchemaObject30 } from 'oas-types/3.0.0';
+
+// OpenAPI 3.1.0
+import { SchemaObject } from 'oas-types/3.1.0';
+
+// OpenAPI 3.1.1
+import { SchemaObject as SchemaObject311 } from 'oas-types/3.1.1';
+
+// Swagger 2.0
+import { SwaggerObject } from 'oas-types/2.0';
+```
+
+### Import Utilities
+
+```typescript
+import { 
+  DeepPartial, 
+  DeepRequired, 
+  Merge, 
+  Versioned,
+  Brand,
+  Nominal 
+} from 'oas-types/utils';
+```
+
+### Import Common Types
+
+```typescript
+import { 
+  HttpMethod,
+  HttpStatusCode,
+  MimeType,
+  JsonSchemaFormat
+} from 'oas-types/common';
+```
+
+## 📁 Project Structure
+
+```
+openapi-types/
+├── src/
+│   ├── atoms/                # Atomic building blocks (common across versions)
+│   │   ├── Contact.ts        # Contact Object
+│   │   ├── License.ts        # License Object
+│   │   ├── Info.ts           # Info Object
+│   │   ├── ExternalDocs.ts   # External Documentation Object
+│   │   ├── Tag.ts            # Tag Object
+│   │   ├── Reference.ts      # Reference Object
+│   │   ├── Server.ts         # Server Object
+│   │   ├── ServerVariable.ts # Server Variable Object
+│   │   └── index.ts          # Exports for all atoms
+│   │
+│   ├── utils/                # Shared helpers for composing, deep partials, etc.
+│   │   └── index.ts
+│   │
+│   ├── 3.0.0/                # Version-specific directory
+│   │   ├── index.ts          # Exports version 3.0.0 types
+│   │   └── schema.ts         # Version-specific overrides/augments
+│   │
+│   ├── 3.0.1/                # Same pattern, with differences from 3.0.0
+│   ├── 3.0.2/
+│   ├── 3.0.3/
+│   ├── 3.0.4/
+│   ├── 3.1.0/
+│   ├── 3.1.1/
+│   └── index.ts              # Public entrypoint (exports all versions + common)
+│
+└── package.json
+```
+
+## 🎯 Philosophy
+
+### Atomic Types (atoms/)
+These are the minimal, composable, strongly typed building blocks — the "vocabulary" of OpenAPI. Examples: `InfoObject`, `ExternalDocumentationObject`, `ContactObject`, `TagObject`, etc.
+
+### Composable Types (version folders)
+Each OpenAPI version folder builds on the atoms and makes modifications for that version. For example:
+- `SchemaObject` in **3.0.0** vs. **3.1.0** (3.1.0 aligns with JSON Schema 2020-12)
+- `CallbackObject` was introduced in **3.0.0** and remains consistent in later versions
+
+### Strictness & Atomic Detail
+Each type follows the spec **literally and atomically** (no "loose" union types unless the spec requires it). For example:
+- Don't just say `string` for a field, define `type UrlString = string;` so it can be reused in multiple contexts
+
+### Version Awareness
+If something is unchanged between versions, **reexport from atoms/**. If something changes, **extend or override** in the version folder.
+
+## 📋 Supported Versions
+
+- **Swagger 2.0** (OpenAPI Specification v2.0)
+- **OpenAPI 3.0.0** - Initial OpenAPI 3.0 release
+- **OpenAPI 3.0.1** - Bug fixes and clarifications
+- **OpenAPI 3.0.2** - Bug fixes and clarifications
+- **OpenAPI 3.0.3** - Bug fixes and clarifications
+- **OpenAPI 3.0.4** - Bug fixes and clarifications
+- **OpenAPI 3.1.0** - Major update with JSON Schema 2020-12 alignment
+- **OpenAPI 3.1.1** - Bug fixes and clarifications
+
+## 🔧 Examples
+
+### Basic Usage
+
+```typescript
+import { InfoObject, ContactObject, LicenseObject } from 'oas-types/atoms';
+
+const info: InfoObject = {
+  title: 'My API',
+  version: '1.0.0',
+  description: 'A sample API',
+  contact: {
+    name: 'API Support',
+    email: 'support@example.com',
+    url: 'https://example.com/support'
+  } as ContactObject,
+  license: {
+    name: 'MIT',
+    url: 'https://opensource.org/licenses/MIT'
+  } as LicenseObject
+};
+```
+
+### Version-Specific Schema Usage
+
+```typescript
+// OpenAPI 3.0.0 schema
+import { SchemaObject30 } from 'oas-types/3.0.0';
+
+const schema30: SchemaObject30 = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'integer', minimum: 0 }
+  },
+  required: ['name'],
+  nullable: true // 3.0.0 specific
+};
+
+// OpenAPI 3.1.0 schema (JSON Schema 2020-12 aligned)
+import { SchemaObject } from 'oas-types/3.1.0';
+
+const schema31: SchemaObject = {
+  type: ['string', 'null'], // 3.1.0 uses union types instead of nullable
+  const: 'example', // 3.1.0 specific
+  pattern: '^[a-zA-Z]+$'
+};
+```
+
+### Using Utilities
+
+```typescript
+import { DeepPartial, Merge, Brand } from 'oas-types/utils';
+import { InfoObject } from 'oas-types/atoms';
+
+// Deep partial for optional configuration
+type PartialConfig = DeepPartial<InfoObject>;
+
+// Merge types
+type ExtendedInfo = Merge<InfoObject, { 
+  customField: string 
+}>;
+
+// Branded types for better type safety
+type UserId = Brand<string, 'UserId'>;
+type ProductId = Brand<string, 'ProductId'>;
+```
+
+## 🧪 Type Safety Features
+
+- **Strict typing** - All types follow the OpenAPI specification exactly
+- **Version awareness** - Type-safe version-specific features
+- **Atomic composition** - Build complex types from simple building blocks
+- **Utility types** - Comprehensive set of helper types for common patterns
+- **JSDoc documentation** - Complete documentation with spec links
+
+## 📚 Documentation
+
+Each type includes comprehensive JSDoc documentation with:
+- Links to the official OpenAPI specification
+- Usage examples
+- Version compatibility notes
+- Type constraints and validation rules
+
+## 🤝 Contributing
+
+Contributions are welcome! Please ensure that:
+- All types follow the OpenAPI specification exactly
+- JSDoc documentation is complete and accurate
+- Version compatibility is maintained
+- Tests are added for new features
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🔗 Links
+
+- [OpenAPI Specification](https://spec.openapis.org/)
+- [Swagger Specification](https://swagger.io/specification/)
+- [JSON Schema](https://json-schema.org/)

bun.lock

@@ -0,0 +1,34 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "openapi-types",
+      "dependencies": {
+        "spdx-license-list": "^6.10.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.22", "", { "dependencies": { "bun-types": "1.2.22" } }, "sha512-5A/KrKos2ZcN0c6ljRSOa1fYIyCKhZfIVYeuyb4snnvomnpFqC0tTsEkdqNxbAgExV384OETQ//WAjl3XbYqQA=="],
+
+    "@types/node": ["@types/node@24.4.0", "", { "dependencies": { "undici-types": "~7.11.0" } }, "sha512-gUuVEAK4/u6F9wRLznPUU4WGUacSEBDPoC2TrBkw3GAnOLHBL45QdfHOXp1kJ4ypBGLxTOB+t7NJLpKoC3gznQ=="],
+
+    "@types/react": ["@types/react@19.1.13", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-hHkbU/eoO3EG5/MZkuFSKmYqPbSVk5byPFa3e7y/8TybHiLMACgI8seVYlicwk7H5K/rI2px9xrQp/C+AUDTiQ=="],
+
+    "bun-types": ["bun-types@1.2.22", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-hwaAu8tct/Zn6Zft4U9BsZcXkYomzpHJX28ofvx7k0Zz2HNz54n1n+tDgxoWFGB4PcFvJXJQloPhaV2eP3Q6EA=="],
+
+    "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
+
+    "spdx-license-list": ["spdx-license-list@6.10.0", "", {}, "sha512-wF3RhDFoqdu14d1Prv6c8aNU0FSRuSFJpNjWeygIZcNZEwPxp7I5/Hwo8j6lSkBKWAIkSQrKefrC5N0lvOP0Gw=="],
+
+    "typescript": ["typescript@5.9.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A=="],
+
+    "undici-types": ["undici-types@7.11.0", "", {}, "sha512-kt1ZriHTi7MU+Z/r9DOdAI3ONdaR3M3csEaRc6ewa4f4dTvX4cQCbJ4NkEn0ohE4hHtq85+PhPSTY+pO/1PwgA=="],
+  }
+}

bunfig.toml

@@ -0,0 +1,8 @@
+[test]
+# Bun test configuration
+preload = ["./tests/setup.ts"]
+
+[install]
+# Install configuration
+cache = true
+production = false

index.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI Types - Comprehensive TypeScript definitions for all OpenAPI versions
+ * @fileoverview Main entry point for OpenAPI type definitions
+ * @version 1.0.0
+ * @since 2024-12-19
+ * 
+ * This library provides comprehensive TypeScript definitions for all OpenAPI specification versions:
+ * - Swagger 2.0 (OpenAPI Specification v2.0)
+ * - OpenAPI 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4
+ * - OpenAPI 3.1.0, 3.1.1
+ * 
+ * The library is organized with atomic building blocks (atoms/) that are shared across versions,
+ * and version-specific implementations that extend or override these atoms as needed.
+ * 
+ * ## Import Paths
+ * 
+ * For the best developer experience, use these import paths:
+ * - `oas-types/atoms` - Atomic building blocks
+ * - `oas-types/utils` - Utility types
+ * - `oas-types/common` - Common types and enums
+ * - `oas-types/3.1.0` - OpenAPI 3.1.0 types
+ * - `oas-types/3.0.0` - OpenAPI 3.0.0 types
+ * - `oas-types/2.0` - Swagger 2.0 types
+ * 
+ * @see {@link https://swagger.io/specification/v2/ Swagger 2.0 Specification}
+ * @see {@link https://spec.openapis.org/oas/v3.0.0 OpenAPI 3.0.0 Specification}
+ * @see {@link https://spec.openapis.org/oas/v3.1.0 OpenAPI 3.1.0 Specification}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1 OpenAPI 3.1.1 Specification}
+ */
+
+// Atomic building blocks - core types shared across all versions
+export * from './versions/atoms';
+
+// Common utilities and shared types
+export * from './versions/common';
+
+// Version-specific exports
+export * as OpenAPI3_0_0 from './versions/3.0.x';
+export * as OpenAPI3_0_1 from './versions/3.0.1';
+export * as OpenAPI3_0_2 from './versions/3.0.2';
+export * as OpenAPI3_0_3 from './versions/3.0.3';
+export * as OpenAPI3_0_4 from './versions/3.0.4';
+export * as OpenAPI3_1_0 from './versions/3.1.0';
+export * as OpenAPI3_1_1 from './versions/3.1.1';

package.json

@@ -0,0 +1,116 @@
+{
+  "name": "oas-types",
+  "version": "1.0.0",
+  "description": "Comprehensive TypeScript definitions for all OpenAPI specification versions (Swagger 2.0, OpenAPI 3.0.0, 3.1.0, 3.1.1)",
+  "main": "index.ts",
+  "module": "index.ts",
+  "type": "module",
+  "types": "index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts"
+    },
+    "./atoms": {
+      "types": "./src/atoms/index.ts",
+      "import": "./src/atoms/index.ts"
+    },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "import": "./src/utils/index.ts"
+    },
+    "./common": {
+      "types": "./src/common.ts",
+      "import": "./src/common.ts"
+    },
+    "./2.0": {
+      "types": "./src/swagger-2.0/index.ts",
+      "import": "./src/swagger-2.0/index.ts"
+    },
+    "./3.0.0": {
+      "types": "./src/3.0.0/index.ts",
+      "import": "./src/3.0.0/index.ts"
+    },
+    "./3.0.1": {
+      "types": "./src/3.0.1/index.ts",
+      "import": "./src/3.0.1/index.ts"
+    },
+    "./3.0.2": {
+      "types": "./src/3.0.2/index.ts",
+      "import": "./src/3.0.2/index.ts"
+    },
+    "./3.0.3": {
+      "types": "./src/3.0.3/index.ts",
+      "import": "./src/3.0.3/index.ts"
+    },
+    "./3.0.4": {
+      "types": "./src/3.0.4/index.ts",
+      "import": "./src/3.0.4/index.ts"
+    },
+    "./3.1.0": {
+      "types": "./src/3.1.0/index.ts",
+      "import": "./src/3.1.0/index.ts"
+    },
+    "./3.1.1": {
+      "types": "./src/3.1.1/index.ts",
+      "import": "./src/3.1.1/index.ts"
+    },
+  },
+  "files": [
+    "src/",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "openapi",
+    "swagger",
+    "typescript",
+    "types",
+    "definitions",
+    "api",
+    "specification",
+    "swagger-2.0",
+    "openapi-3.0.0",
+    "openapi-3.1.0",
+    "openapi-3.1.1",
+    "json-schema",
+    "rest",
+    "api-documentation"
+  ],
+  "author": "OpenAPI Types Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/openapi-types.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-username/openapi-types/issues"
+  },
+  "homepage": "https://github.com/your-username/openapi-types#readme",
+  "dependencies": {
+    "spdx-license-list": "^6.10.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:common": "bun test tests/common.test.ts",
+    "test:open-enums": "bun test tests/open-enums.test.ts",
+    "test:swagger-2.0": "bun test tests/swagger-2.0.test.ts",
+    "test:openapi-3.0.0": "bun test tests/openapi-3.0.0.test.ts",
+    "test:integration": "bun test tests/integration.test.ts",
+    "type-check": "tsc --noEmit",
+    "build": "tsc",
+    "dev": "bun run --watch index.ts"
+  }
+}

tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

versions/2.0.0/data-types/array.ts

@@ -0,0 +1,160 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Array Schema
+ * -----
+ *
+ * Schema for array data types in Swagger 2.0.
+ * 
+ * Array schemas represent ordered collections of items, where each item conforms
+ * to a specified schema. They are based on JSON Schema Draft 4 with Swagger-specific
+ * adjustments, providing comprehensive validation for array data structures.
+ *
+ * Array schemas are commonly used for lists, collections, and ordered data in APIs.
+ * They support validation of array length, item uniqueness, and item type constraints.
+ * The items property defines the schema that each array element must conform to.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "array" for array schemas.
+ * @key `items` - Required. Describes the type of items in the array.
+ * @key `description` - A short description of the array schema.
+ * @key `title` - A short title for the array schema.
+ * @key `default` - Declares the default value for the array.
+ * @key `maxItems` - Maximum number of items in the array.
+ * @key `minItems` - Minimum number of items in the array.
+ * @key `uniqueItems` - Whether all items in the array must be unique.
+ * @key `example` - Example array value.
+ *
+ * @note
+ * Array schemas inherit common properties from BaseSchemaProperties and add
+ * array-specific validation properties. The `items` property is required and
+ * defines the schema for each array element.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (string array):
+ * ```ts
+ * const tagsSchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   description: "List of tags",
+ *   minItems: 1,
+ *   maxItems: 10,
+ *   uniqueItems: true,
+ *   example: ["javascript", "api", "swagger"]
+ * };
+ * ```
+ *
+ * @example (object array):
+ * ```ts
+ * const usersSchema: ArraySchema = {
+ *   type: "array",
+ *   items: { $ref: "#/definitions/User" },
+ *   description: "List of users",
+ *   minItems: 0,
+ *   maxItems: 100,
+ *   example: [
+ *     { id: 1, name: "John Doe" },
+ *     { id: 2, name: "Jane Smith" }
+ *   ]
+ * };
+ * ```
+ *
+ * @example (number array):
+ * ```ts
+ * const scoresSchema: ArraySchema = {
+ *   type: "array",
+ *   items: { 
+ *     type: "number",
+ *     minimum: 0,
+ *     maximum: 100
+ *   },
+ *   description: "Test scores",
+ *   minItems: 1,
+ *   maxItems: 50,
+ *   example: [85, 92, 78, 96]
+ * };
+ * ```
+ *
+ * @example (nested array):
+ * ```ts
+ * const matrixSchema: ArraySchema = {
+ *   type: "array",
+ *   items: {
+ *     type: "array",
+ *     items: { type: "number" },
+ *     minItems: 3,
+ *     maxItems: 3
+ *   },
+ *   description: "3x3 matrix",
+ *   minItems: 3,
+ *   maxItems: 3,
+ *   example: [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
+ * };
+ * ```
+ */
+export interface ArraySchema extends Extension {
+  /**
+   * The type of the schema. Must be "array" for array schemas.
+   * 
+   * This property is required and must be set to "array" to indicate
+   * that this schema represents an ordered collection of items.
+   * 
+   * @example "array"
+   */
+  type: "array"
+  
+  /**
+   * Required if type is "array". Describes the type of items in the array.
+   * 
+   * The definition is the same as the one from JSON Schema, but references 
+   * the Swagger Schema Object definition instead. This allows for complex
+   * nested structures and references to other schema definitions.
+   * 
+   * @example { type: "string" }
+   * @example { $ref: "#/definitions/User" }
+   * @example { type: "object", properties: { name: { type: "string" } } }
+   */
+  items: any // Forward declaration to avoid circular imports
+  
+  /**
+   * An array is valid against "maxItems" if its length is less than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 | JSON Schema Validation - maxItems}
+   * 
+   * @example 10
+   * @example 100
+   */
+  maxItems?: number
+  
+  /**
+   * An array is valid against "minItems" if its length is greater than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 | JSON Schema Validation - minItems}
+   * 
+   * @example 1
+   * @example 2
+   */
+  minItems?: number
+  
+  /**
+   * An array is valid against "uniqueItems" if all its elements are unique.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 | JSON Schema Validation - uniqueItems}
+   * 
+   * @example true
+   * @example false
+   */
+  uniqueItems?: boolean
+}

versions/2.0.0/data-types/boolean.ts

@@ -0,0 +1,172 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Boolean Schema
+ * -----
+ *
+ * Schema for boolean data types in Swagger 2.0.
+ * 
+ * Boolean schemas represent true/false values and are used for flags, switches,
+ * and other binary state indicators in APIs. They are simple but essential
+ * data types that provide clear semantic meaning for binary choices.
+ *
+ * Boolean schemas are commonly used for feature flags, status indicators,
+ * configuration options, and other binary state representations. They support
+ * default values and examples to help API consumers understand the expected
+ * behavior.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "boolean" for boolean schemas.
+ * @key `description` - A short description of the boolean schema.
+ * @key `title` - A short title for the boolean schema.
+ * @key `default` - Declares the default value for the boolean.
+ * @key `example` - Example boolean value.
+ *
+ * @note
+ * Boolean schemas inherit common properties from BaseSchemaProperties.
+ * No additional validation properties are needed for boolean values as they
+ * are inherently simple (true/false only).
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (feature flag boolean):
+ * ```ts
+ * const featureFlagSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   description: "Whether the new feature is enabled",
+ *   default: false,
+ *   example: true
+ * };
+ * ```
+ *
+ * @example (status boolean):
+ * ```ts
+ * const isActiveSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   description: "Whether the user account is active",
+ *   default: true,
+ *   example: true
+ * };
+ * ```
+ *
+ * @example (configuration boolean):
+ * ```ts
+ * const notificationsEnabledSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   description: "Whether email notifications are enabled",
+ *   default: true,
+ *   example: false
+ * };
+ * ```
+ *
+ * @example (permission boolean):
+ * ```ts
+ * const canEditSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   description: "Whether the user can edit this resource",
+ *   example: true
+ * };
+ * ```
+ */
+export interface BooleanSchema extends Extension {
+  /**
+   * The type of the schema. Must be "boolean" for boolean schemas.
+   * 
+   * This property is required and must be set to "boolean" to indicate
+   * that this schema represents true/false values.
+   * 
+   * @example "boolean"
+   */
+  type: "boolean"
+  
+  /**
+   * The extending format for the previously mentioned type. 
+   * See Swagger 2.0 Data Type Formats for further details.
+   * 
+   * Formats provide additional semantic information about the data type,
+   * enabling more precise validation and better tooling support. Swagger 2.0
+   * defines several standard formats, but custom formats are also allowed.
+   * 
+   * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats}
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   * @example "uuid"
+   */
+  format?: string
+  
+  /**
+   * A short description of the schema. GFM syntax can be used for rich text representation.
+   * 
+   * This description should provide clear information about what the schema
+   * represents and how it should be used. It's commonly displayed in API
+   * documentation and code generation tools.
+   * 
+   * @example "A user object containing basic information"
+   * @example "Email address in RFC 5322 format"
+   */
+  description?: string
+  
+  /**
+   * A short title for the schema.
+   * 
+   * The title provides a human-readable name for the schema, often used
+   * in documentation and UI displays. It should be concise but descriptive.
+   * 
+   * @example "User"
+   * @example "Pet"
+   * @example "Order"
+   */
+  title?: string
+  
+  /**
+   * Declares the value of the schema that the server will use if none is provided.
+   * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object.
+   * 
+   * This is a Swagger 2.0 specific requirement that differs from JSON Schema.
+   * The default value must be valid according to the schema's type and constraints.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   * @example { name: "John", age: 30 }
+   * @example ["item1", "item2"]
+   */
+  default?: unknown
+  
+  /**
+   * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum}
+   * 
+   * @example ["option1", "option2", "option3"]
+   * @example ["red", "green", "blue"]
+   * @example [1, 2, 3, 4, 5]
+   */
+  enum?: unknown[]
+  
+  /**
+   * A free-form property to include an example of an instance for this schema.
+   * 
+   * Examples help developers understand how to use the schema and what kind
+   * of data is expected. They are commonly used by documentation generators
+   * and API testing tools.
+   * 
+   * @example { name: "Puma", id: 1 }
+   * @example "example string value"
+   * @example 42
+   * @example ["item1", "item2"]
+   */
+  example?: unknown
+}

versions/2.0.0/data-types/file.ts

@@ -0,0 +1,171 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * File Schema
+ * -----
+ *
+ * Schema for file data types in Swagger 2.0.
+ * 
+ * File schemas represent file uploads and downloads in APIs. This is a Swagger 2.0
+ * specific data type that extends the JSON Schema specification to support file
+ * operations. File schemas are used by Parameter and Response objects to indicate
+ * that the data represents a file rather than a structured data type.
+ *
+ * File schemas are commonly used for file upload endpoints, document processing,
+ * image handling, and other file-based operations. They provide clear indication
+ * to API consumers that file data is expected or returned.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#response-object | Swagger 2.0 Response Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "file" for file schemas.
+ * @key `description` - A short description of the file schema.
+ * @key `title` - A short title for the file schema.
+ * @key `example` - Example file information or description.
+ *
+ * @note
+ * File schemas are specific to Swagger 2.0 and are not part of the JSON Schema
+ * specification. They inherit common properties from BaseSchemaProperties.
+ * When used in parameters, the consumes property should specify appropriate
+ * MIME types like "multipart/form-data" or "application/x-www-form-urlencoded".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (file upload parameter):
+ * ```ts
+ * const fileUploadSchema: FileSchema = {
+ *   type: "file",
+ *   description: "Image file to upload",
+ *   example: "user-avatar.jpg"
+ * };
+ * ```
+ *
+ * @example (document upload parameter):
+ * ```ts
+ * const documentSchema: FileSchema = {
+ *   type: "file",
+ *   description: "PDF document to process",
+ *   example: "contract.pdf"
+ * };
+ * ```
+ *
+ * @example (file download response):
+ * ```ts
+ * const fileDownloadSchema: FileSchema = {
+ *   type: "file",
+ *   description: "Generated report file",
+ *   example: "monthly-report.xlsx"
+ * };
+ * ```
+ *
+ * @example (image file parameter):
+ * ```ts
+ * const imageSchema: FileSchema = {
+ *   type: "file",
+ *   description: "Profile picture image",
+ *   example: "profile-photo.png"
+ * };
+ * ```
+ */
+export interface FileSchema extends Extension {
+  /**
+   * The type of the schema. Must be "file" for file schemas.
+   * 
+   * This property is required and must be set to "file" to indicate
+   * that this schema represents file data. This is a Swagger 2.0 specific
+   * type that extends JSON Schema.
+   * 
+   * @example "file"
+   */
+  type: "file"
+  
+  /**
+   * The extending format for the previously mentioned type. 
+   * See Swagger 2.0 Data Type Formats for further details.
+   * 
+   * Formats provide additional semantic information about the data type,
+   * enabling more precise validation and better tooling support. Swagger 2.0
+   * defines several standard formats, but custom formats are also allowed.
+   * 
+   * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats}
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   * @example "uuid"
+   */
+  format?: string
+  
+  /**
+   * A short description of the schema. GFM syntax can be used for rich text representation.
+   * 
+   * This description should provide clear information about what the schema
+   * represents and how it should be used. It's commonly displayed in API
+   * documentation and code generation tools.
+   * 
+   * @example "A user object containing basic information"
+   * @example "Email address in RFC 5322 format"
+   */
+  description?: string
+  
+  /**
+   * A short title for the schema.
+   * 
+   * The title provides a human-readable name for the schema, often used
+   * in documentation and UI displays. It should be concise but descriptive.
+   * 
+   * @example "User"
+   * @example "Pet"
+   * @example "Order"
+   */
+  title?: string
+  
+  /**
+   * Declares the value of the schema that the server will use if none is provided.
+   * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object.
+   * 
+   * This is a Swagger 2.0 specific requirement that differs from JSON Schema.
+   * The default value must be valid according to the schema's type and constraints.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   * @example { name: "John", age: 30 }
+   * @example ["item1", "item2"]
+   */
+  default?: unknown
+  
+  /**
+   * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum}
+   * 
+   * @example ["option1", "option2", "option3"]
+   * @example ["red", "green", "blue"]
+   * @example [1, 2, 3, 4, 5]
+   */
+  enum?: unknown[]
+  
+  /**
+   * A free-form property to include an example of an instance for this schema.
+   * 
+   * Examples help developers understand how to use the schema and what kind
+   * of data is expected. They are commonly used by documentation generators
+   * and API testing tools.
+   * 
+   * @example { name: "Puma", id: 1 }
+   * @example "example string value"
+   * @example 42
+   * @example ["item1", "item2"]
+   */
+  example?: unknown
+}

versions/2.0.0/data-types/index.ts

@@ -0,0 +1,14 @@
+// Base schema properties
+export type { BaseSchemaProperties } from "./base-schema"
+
+// Individual schema types
+export type { StringSchema } from "./string"
+export type { NumberSchema } from "./number"
+export type { IntegerSchema } from "./integer"
+export type { BooleanSchema } from "./boolean"
+export type { FileSchema } from "./file"
+export type { ArraySchema } from "./array"
+export type { ObjectSchema } from "./object"
+
+// Main schema union type
+export type { SwaggerSchema } from "./swagger-schema"

versions/2.0.0/data-types/integer.ts

@@ -0,0 +1,234 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Integer Schema
+ * -----
+ *
+ * Schema for integer data types in Swagger 2.0.
+ * 
+ * Integer schemas represent whole numbers without fractional components.
+ * They support various formats and validation rules to ensure data integrity
+ * and provide meaningful constraints for integer values.
+ *
+ * Integer schemas are commonly used for counts, IDs, timestamps, and other
+ * discrete numeric values in APIs. They support range validation and multiple
+ * format specifications including int32 and int64.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "integer" for integer schemas.
+ * @key `format` - The extending format for the integer type (e.g., "int32", "int64").
+ * @key `description` - A short description of the integer schema.
+ * @key `title` - A short title for the integer schema.
+ * @key `default` - Declares the default value for the integer.
+ * @key `multipleOf` - The integer must be a multiple of this value.
+ * @key `maximum` - Maximum value for the integer.
+ * @key `exclusiveMaximum` - Whether the maximum value is exclusive.
+ * @key `minimum` - Minimum value for the integer.
+ * @key `exclusiveMinimum` - Whether the minimum value is exclusive.
+ * @key `example` - Example integer value.
+ *
+ * @note
+ * Integer schemas inherit common properties from BaseSchemaProperties and add
+ * numeric-specific validation properties. The `format` property is important
+ * for distinguishing between different integer representations (int32 vs int64).
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (user ID integer):
+ * ```ts
+ * const userIdSchema: IntegerSchema = {
+ *   type: "integer",
+ *   format: "int64",
+ *   description: "Unique user identifier",
+ *   minimum: 1,
+ *   example: 12345
+ * };
+ * ```
+ *
+ * @example (age integer):
+ * ```ts
+ * const ageSchema: IntegerSchema = {
+ *   type: "integer",
+ *   format: "int32",
+ *   description: "Person's age in years",
+ *   minimum: 0,
+ *   maximum: 150,
+ *   example: 25
+ * };
+ * ```
+ *
+ * @example (quantity integer):
+ * ```ts
+ * const quantitySchema: IntegerSchema = {
+ *   type: "integer",
+ *   format: "int32",
+ *   description: "Item quantity",
+ *   minimum: 0,
+ *   maximum: 1000,
+ *   multipleOf: 1,
+ *   example: 5
+ * };
+ * ```
+ *
+ * @example (timestamp integer):
+ * ```ts
+ * const timestampSchema: IntegerSchema = {
+ *   type: "integer",
+ *   format: "int64",
+ *   description: "Unix timestamp in seconds",
+ *   minimum: 0,
+ *   example: 1640995200
+ * };
+ * ```
+ */
+export interface IntegerSchema extends Extension {
+  /**
+   * The type of the schema. Must be "integer" for integer schemas.
+   * 
+   * This property is required and must be set to "integer" to indicate
+   * that this schema represents whole number data without fractional components.
+   * 
+   * @example "integer"
+   */
+  type: "integer"
+  
+  /**
+   * The extending format for the previously mentioned type. 
+   * See Swagger 2.0 Data Type Formats for further details.
+   * 
+   * Formats provide additional semantic information about the data type,
+   * enabling more precise validation and better tooling support. Swagger 2.0
+   * defines several standard formats, but custom formats are also allowed.
+   * 
+   * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats}
+   * 
+   * @example "int32"
+   * @example "int64"
+   */
+  format?: string
+  
+  /**
+   * A short description of the schema. GFM syntax can be used for rich text representation.
+   * 
+   * This description should provide clear information about what the schema
+   * represents and how it should be used. It's commonly displayed in API
+   * documentation and code generation tools.
+   * 
+   * @example "A user object containing basic information"
+   * @example "Email address in RFC 5322 format"
+   */
+  description?: string
+  
+  /**
+   * A short title for the schema.
+   * 
+   * The title provides a human-readable name for the schema, often used
+   * in documentation and UI displays. It should be concise but descriptive.
+   * 
+   * @example "User"
+   * @example "Pet"
+   * @example "Order"
+   */
+  title?: string
+  
+  /**
+   * Declares the value of the schema that the server will use if none is provided.
+   * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object.
+   * 
+   * This is a Swagger 2.0 specific requirement that differs from JSON Schema.
+   * The default value must be valid according to the schema's type and constraints.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   * @example { name: "John", age: 30 }
+   * @example ["item1", "item2"]
+   */
+  default?: unknown
+  
+  /**
+   * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum}
+   * 
+   * @example ["option1", "option2", "option3"]
+   * @example ["red", "green", "blue"]
+   * @example [1, 2, 3, 4, 5]
+   */
+  enum?: unknown[]
+  
+  /**
+   * A free-form property to include an example of an instance for this schema.
+   * 
+   * Examples help developers understand how to use the schema and what kind
+   * of data is expected. They are commonly used by documentation generators
+   * and API testing tools.
+   * 
+   * @example { name: "Puma", id: 1 }
+   * @example "example string value"
+   * @example 42
+   * @example ["item1", "item2"]
+   */
+  example?: unknown
+  
+  /**
+   * A number is valid against "multipleOf" if the result of the division
+   * of the instance by this keyword's value is an integer.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 | JSON Schema Validation - multipleOf}
+   * 
+   * @example 2
+   * @example 1
+   */
+  multipleOf?: number
+  
+  /**
+   * A number is valid against "maximum" if it is less than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - maximum}
+   * 
+   * @example 100
+   * @example 2147483647
+   */
+  maximum?: number
+  
+  /**
+   * A number is valid against "exclusiveMaximum" if it is strictly less than this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - exclusiveMaximum}
+   * 
+   * @example false
+   * @example true
+   */
+  exclusiveMaximum?: boolean
+  
+  /**
+   * A number is valid against "minimum" if it is greater than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - minimum}
+   * 
+   * @example 0
+   * @example 1
+   */
+  minimum?: number
+  
+  /**
+   * A number is valid against "exclusiveMinimum" if it is strictly greater than this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - exclusiveMinimum}
+   * 
+   * @example false
+   * @example true
+   */
+  exclusiveMinimum?: boolean
+}

versions/2.0.0/data-types/number.ts

@@ -0,0 +1,239 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Number Schema
+ * -----
+ *
+ * Schema for number data types in Swagger 2.0.
+ * 
+ * Number schemas represent numeric data including both integers and floating-point
+ * numbers. They support various formats and validation rules to ensure data
+ * integrity and provide meaningful constraints for numeric values.
+ *
+ * Number schemas are commonly used for quantities, prices, measurements, and
+ * other numeric data in APIs. They support range validation, precision control,
+ * and multiple format specifications.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "number" for number schemas.
+ * @key `format` - The extending format for the number type (e.g., "float", "double").
+ * @key `description` - A short description of the number schema.
+ * @key `title` - A short title for the number schema.
+ * @key `default` - Declares the default value for the number.
+ * @key `multipleOf` - The number must be a multiple of this value.
+ * @key `maximum` - Maximum value for the number.
+ * @key `exclusiveMaximum` - Whether the maximum value is exclusive.
+ * @key `minimum` - Minimum value for the number.
+ * @key `exclusiveMinimum` - Whether the minimum value is exclusive.
+ * @key `example` - Example number value.
+ *
+ * @note
+ * Number schemas inherit common properties from BaseSchemaProperties and add
+ * numeric-specific validation properties. The `format` property is important
+ * for distinguishing between different numeric representations (float vs double).
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (price number):
+ * ```ts
+ * const priceSchema: NumberSchema = {
+ *   type: "number",
+ *   format: "double",
+ *   description: "Price in USD",
+ *   minimum: 0,
+ *   maximum: 999999.99,
+ *   multipleOf: 0.01,
+ *   example: 29.99
+ * };
+ * ```
+ *
+ * @example (percentage number):
+ * ```ts
+ * const percentageSchema: NumberSchema = {
+ *   type: "number",
+ *   format: "float",
+ *   description: "Percentage value",
+ *   minimum: 0,
+ *   maximum: 100,
+ *   example: 85.5
+ * };
+ * ```
+ *
+ * @example (coordinate number):
+ * ```ts
+ * const coordinateSchema: NumberSchema = {
+ *   type: "number",
+ *   format: "double",
+ *   description: "Geographic coordinate",
+ *   minimum: -180,
+ *   maximum: 180,
+ *   example: -122.4194
+ * };
+ * ```
+ *
+ * @example (rating number):
+ * ```ts
+ * const ratingSchema: NumberSchema = {
+ *   type: "number",
+ *   format: "float",
+ *   description: "User rating",
+ *   minimum: 1,
+ *   maximum: 5,
+ *   multipleOf: 0.1,
+ *   example: 4.5
+ * };
+ * ```
+ */
+export interface NumberSchema extends Extension {
+  /**
+   * The type of the schema. Must be "number" for number schemas.
+   * 
+   * This property is required and must be set to "number" to indicate
+   * that this schema represents numeric data (both integers and floating-point).
+   * 
+   * @example "number"
+   */
+  type: "number"
+  
+  /**
+   * The extending format for the previously mentioned type. 
+   * See Swagger 2.0 Data Type Formats for further details.
+   * 
+   * Formats provide additional semantic information about the data type,
+   * enabling more precise validation and better tooling support. Swagger 2.0
+   * defines several standard formats, but custom formats are also allowed.
+   * 
+   * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats}
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   * @example "uuid"
+   */
+  format?: string
+  
+  /**
+   * A short description of the schema. GFM syntax can be used for rich text representation.
+   * 
+   * This description should provide clear information about what the schema
+   * represents and how it should be used. It's commonly displayed in API
+   * documentation and code generation tools.
+   * 
+   * @example "A user object containing basic information"
+   * @example "Email address in RFC 5322 format"
+   */
+  description?: string
+  
+  /**
+   * A short title for the schema.
+   * 
+   * The title provides a human-readable name for the schema, often used
+   * in documentation and UI displays. It should be concise but descriptive.
+   * 
+   * @example "User"
+   * @example "Pet"
+   * @example "Order"
+   */
+  title?: string
+  
+  /**
+   * Declares the value of the schema that the server will use if none is provided.
+   * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object.
+   * 
+   * This is a Swagger 2.0 specific requirement that differs from JSON Schema.
+   * The default value must be valid according to the schema's type and constraints.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   * @example { name: "John", age: 30 }
+   * @example ["item1", "item2"]
+   */
+  default?: unknown
+  
+  /**
+   * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum}
+   * 
+   * @example ["option1", "option2", "option3"]
+   * @example ["red", "green", "blue"]
+   * @example [1, 2, 3, 4, 5]
+   */
+  enum?: unknown[]
+  
+  /**
+   * A free-form property to include an example of an instance for this schema.
+   * 
+   * Examples help developers understand how to use the schema and what kind
+   * of data is expected. They are commonly used by documentation generators
+   * and API testing tools.
+   * 
+   * @example { name: "Puma", id: 1 }
+   * @example "example string value"
+   * @example 42
+   * @example ["item1", "item2"]
+   */
+  example?: unknown
+  
+  /**
+   * A number is valid against "multipleOf" if the result of the division
+   * of the instance by this keyword's value is an integer.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 | JSON Schema Validation - multipleOf}
+   * 
+   * @example 2
+   * @example 0.01
+   */
+  multipleOf?: number
+  
+  /**
+   * A number is valid against "maximum" if it is less than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - maximum}
+   * 
+   * @example 100
+   * @example 999.99
+   */
+  maximum?: number
+  
+  /**
+   * A number is valid against "exclusiveMaximum" if it is strictly less than this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - exclusiveMaximum}
+   * 
+   * @example false
+   * @example true
+   */
+  exclusiveMaximum?: boolean
+  
+  /**
+   * A number is valid against "minimum" if it is greater than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - minimum}
+   * 
+   * @example 0
+   * @example 1
+   */
+  minimum?: number
+  
+  /**
+   * A number is valid against "exclusiveMinimum" if it is strictly greater than this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - exclusiveMinimum}
+   * 
+   * @example false
+   * @example true
+   */
+  exclusiveMinimum?: boolean
+}

versions/2.0.0/data-types/object.ts

@@ -0,0 +1,205 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Object Schema
+ * -----
+ *
+ * Schema for object data types in Swagger 2.0.
+ * 
+ * Object schemas represent structured data with named properties, where each
+ * property has its own schema definition. They are based on JSON Schema Draft 4
+ * with Swagger-specific adjustments, providing comprehensive validation for
+ * complex data structures.
+ *
+ * Object schemas are commonly used for models, entities, and complex data
+ * structures in APIs. They support property definitions, required fields,
+ * additional properties, and composition through allOf. The properties
+ * reference Swagger Schema Objects instead of JSON Schema definitions.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "object" for object schemas.
+ * @key `properties` - The properties of the object.
+ * @key `required` - A list of required properties.
+ * @key `additionalProperties` - Additional properties for the object.
+ * @key `allOf` - An array of schemas that this schema must validate against.
+ * @key `description` - A short description of the object schema.
+ * @key `title` - A short title for the object schema.
+ * @key `default` - Declares the default value for the object.
+ * @key `maxProperties` - Maximum number of properties in the object.
+ * @key `minProperties` - Minimum number of properties in the object.
+ * @key `example` - Example object value.
+ *
+ * @note
+ * Object schemas inherit common properties from BaseSchemaProperties and add
+ * object-specific validation properties. The properties, additionalProperties,
+ * and allOf definitions reference the Swagger Schema Object instead of JSON Schema.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple object):
+ * ```ts
+ * const userSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     id: { type: "integer", format: "int64" },
+ *     name: { type: "string" },
+ *     email: { type: "string", format: "email" }
+ *   },
+ *   required: ["id", "name", "email"],
+ *   example: { id: 1, name: "John Doe", email: "john@example.com" }
+ * };
+ * ```
+ *
+ * @example (object with additional properties):
+ * ```ts
+ * const configSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     theme: { type: "string", enum: ["light", "dark"] },
+ *     language: { type: "string", default: "en" }
+ *   },
+ *   additionalProperties: { type: "string" },
+ *   description: "User configuration with custom properties"
+ * };
+ * ```
+ *
+ * @example (object with composition):
+ * ```ts
+ * const extendedUserSchema: ObjectSchema = {
+ *   type: "object",
+ *   allOf: [
+ *     { $ref: "#/definitions/BaseUser" },
+ *     {
+ *       type: "object",
+ *       properties: {
+ *         role: { type: "string", enum: ["admin", "user", "guest"] },
+ *         permissions: { type: "array", items: { type: "string" } }
+ *       },
+ *       required: ["role"]
+ *     }
+ *   ],
+ *   description: "Extended user with role and permissions"
+ * };
+ * ```
+ *
+ * @example (nested object):
+ * ```ts
+ * const addressSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     street: { type: "string" },
+ *     city: { type: "string" },
+ *     state: { type: "string" },
+ *     zipCode: { type: "string", pattern: "^\\d{5}(-\\d{4})?$" },
+ *     country: { type: "string", default: "US" }
+ *   },
+ *   required: ["street", "city", "state", "zipCode"],
+ *   example: {
+ *     street: "123 Main St",
+ *     city: "Anytown",
+ *     state: "CA",
+ *     zipCode: "12345",
+ *     country: "US"
+ *   }
+ * };
+ * ```
+ */
+export interface ObjectSchema extends Extension {
+  /**
+   * The type of the schema. Must be "object" for object schemas.
+   * 
+   * This property is required and must be set to "object" to indicate
+   * that this schema represents structured data with named properties.
+   * 
+   * @example "object"
+   */
+  type: "object"
+  
+  /**
+   * The properties of the object. The definition is the same as the one from 
+   * JSON Schema, but references the Swagger Schema Object definition instead.
+   * 
+   * Each property name maps to a schema definition that describes the type
+   * and validation rules for that property. Properties can be of any type
+   * supported by Swagger schemas, including primitives, objects, arrays,
+   * and references.
+   * 
+   * @example { name: { type: "string" }, age: { type: "integer" } }
+   * @example { address: { $ref: "#/definitions/Address" } }
+   */
+  properties?: Record<string, any> // Forward declaration to avoid circular imports
+  
+  /**
+   * A list of required properties. Properties marked as required being true 
+   * MUST be present in the object.
+   * 
+   * This array contains the names of properties that must be present in
+   * any valid instance of this object schema. Properties not listed here
+   * are considered optional.
+   * 
+   * @example ["name", "email"]
+   * @example ["id", "type", "createdAt"]
+   */
+  required?: string[]
+  
+  /**
+   * Additional properties for the object. Can be a boolean or a schema.
+   * The definition is the same as the one from JSON Schema, but references 
+   * the Swagger Schema Object definition instead.
+   * 
+   * - If true, additional properties of any type are allowed
+   * - If false, no additional properties are allowed
+   * - If a schema, additional properties must conform to that schema
+   * 
+   * @example true
+   * @example false
+   * @example { type: "string" }
+   * @example { $ref: "#/definitions/AdditionalProperty" }
+   */
+  additionalProperties?: boolean | any // Forward declaration to avoid circular imports
+  
+  /**
+   * An array of schemas that this schema must validate against.
+   * All schemas in the array must be valid for the object to be valid.
+   * The definition is the same as the one from JSON Schema, but references 
+   * the Swagger Schema Object definition instead.
+   * 
+   * This enables schema composition and inheritance patterns, allowing
+   * objects to extend or combine multiple base schemas.
+   * 
+   * @example [{ $ref: "#/definitions/BaseUser" }, { type: "object", properties: { ... } }]
+   * @example [{ $ref: "#/definitions/Identifiable" }, { $ref: "#/definitions/Timestamped" }]
+   */
+  allOf?: any[] // Forward declaration to avoid circular imports
+  
+  /**
+   * An object is valid against "maxProperties" if its number of properties is less than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.4.1 | JSON Schema Validation - maxProperties}
+   * 
+   * @example 10
+   * @example 50
+   */
+  maxProperties?: number
+  
+  /**
+   * An object is valid against "minProperties" if its number of properties is greater than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.4.2 | JSON Schema Validation - minProperties}
+   * 
+   * @example 1
+   * @example 2
+   */
+  minProperties?: number
+}

versions/2.0.0/data-types/schema.ts

@@ -0,0 +1,107 @@
+import type { BaseReference } from "../references"
+import type { StringSchema } from "./string"
+import type { NumberSchema } from "./number"
+import type { IntegerSchema } from "./integer"
+import type { BooleanSchema } from "./boolean"
+import type { FileSchema } from "./file"
+import type { ArraySchema } from "./array"
+import type { ObjectSchema } from "./object"
+
+/**
+ * -----
+ * Schema
+ * -----
+ *
+ * The complete schema type for Swagger 2.0, which includes all possible schema types
+ * plus Swagger-specific extensions. This is the union type that represents any valid
+ * schema definition in a Swagger 2.0 specification.
+ *
+ * Swagger schemas are based on JSON Schema Draft 4 with Swagger-specific extensions
+ * and the additional "file" type. They provide comprehensive validation capabilities
+ * for all data types supported by the Swagger 2.0 specification.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ *
+ * -----
+ * Schema Types
+ * -----
+ *
+ * @key `StringSchema` - String data types with format and validation
+ * @key `NumberSchema` - Numeric data types (floating-point)
+ * @key `IntegerSchema` - Integer data types (whole numbers)
+ * @key `BooleanSchema` - Boolean data types (true/false)
+ * @key `FileSchema` - File data types (Swagger 2.0 specific)
+ * @key `ArraySchema` - Array data types with item validation
+ * @key `ObjectSchema` - Object data types with property definitions
+ * @key `BaseReference` - JSON Reference to other schema definitions
+ *
+ * @note
+ * All schema types inherit from BaseSchemaProperties and support
+ * comprehensive validation rules. The "file" type is specific to
+ * Swagger 2.0 and not part of the JSON Schema specification.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (string schema):
+ * ```ts
+ * const stringSchema: Schema = {
+ *   type: "string",
+ *   format: "email",
+ *   description: "User email address",
+ *   pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+ * };
+ * ```
+ *
+ * @example (object schema):
+ * ```ts
+ * const userSchema: Schema = {
+ *   type: "object",
+ *   properties: {
+ *     id: { type: "integer", format: "int64" },
+ *     name: { type: "string" },
+ *     email: { type: "string", format: "email" }
+ *   },
+ *   required: ["id", "name", "email"]
+ * };
+ * ```
+ *
+ * @example (array schema):
+ * ```ts
+ * const tagsSchema: Schema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   minItems: 1,
+ *   maxItems: 10,
+ *   uniqueItems: true
+ * };
+ * ```
+ *
+ * @example (reference schema):
+ * ```ts
+ * const refSchema: Schema = {
+ *   $ref: "#/definitions/User"
+ * };
+ * ```
+ *
+ * @example (file schema):
+ * ```ts
+ * const fileSchema: Schema = {
+ *   type: "file",
+ *   description: "Image file to upload"
+ * };
+ * ```
+ */
+export type Schema = 
+  | StringSchema
+  | NumberSchema
+  | IntegerSchema
+  | BooleanSchema
+  | FileSchema
+  | ArraySchema
+  | ObjectSchema
+  | BaseReference

versions/2.0.0/data-types/string.ts

@@ -0,0 +1,215 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * String Schema
+ * -----
+ *
+ * Schema for string data types in Swagger 2.0.
+ * 
+ * String schemas represent textual data and support various formats and validation
+ * rules. They are one of the most commonly used schema types in API specifications,
+ * used for names, descriptions, identifiers, and other text-based data.
+ *
+ * String schemas support a wide range of formats including standard formats like
+ * email, date, and UUID, as well as custom formats defined by the API provider.
+ * They also support comprehensive validation through pattern matching, length
+ * constraints, and enumeration.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "string" for string schemas.
+ * @key `format` - The extending format for the string type. See Data Type Formats for further details.
+ * @key `description` - A short description of the string schema.
+ * @key `title` - A short title for the string schema.
+ * @key `default` - Declares the default value for the string.
+ * @key `maxLength` - Maximum length of the string.
+ * @key `minLength` - Minimum length of the string.
+ * @key `pattern` - Regular expression pattern the string must match.
+ * @key `enum` - Array of allowed string values.
+ * @key `example` - Example string value.
+ *
+ * @note
+ * String schemas include only properties that are valid for string types.
+ * This ensures type safety and prevents invalid property combinations.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (email string):
+ * ```ts
+ * const emailSchema: StringSchema = {
+ *   type: "string",
+ *   format: "email",
+ *   description: "User email address",
+ *   pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+ *   maxLength: 254,
+ *   minLength: 5,
+ *   example: "user@example.com"
+ * };
+ * ```
+ *
+ * @example (date string):
+ * ```ts
+ * const dateSchema: StringSchema = {
+ *   type: "string",
+ *   format: "date",
+ *   description: "Date in YYYY-MM-DD format",
+ *   pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+ *   example: "2023-12-25"
+ * };
+ * ```
+ *
+ * @example (enum string):
+ * ```ts
+ * const statusSchema: StringSchema = {
+ *   type: "string",
+ *   description: "Order status",
+ *   enum: ["pending", "processing", "shipped", "delivered", "cancelled"],
+ *   default: "pending",
+ *   example: "pending"
+ * };
+ * ```
+ *
+ * @example (custom format string):
+ * ```ts
+ * const uuidSchema: StringSchema = {
+ *   type: "string",
+ *   format: "uuid",
+ *   description: "Universally unique identifier",
+ *   pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+ *   example: "550e8400-e29b-41d4-a716-446655440000"
+ * };
+ * ```
+ */
+export interface StringSchema extends Extension {
+  /**
+   * The type of the schema. Must be "string" for string schemas.
+   * 
+   * This property is required and must be set to "string" to indicate
+   * that this schema represents string data.
+   * 
+   * @example "string"
+   */
+  type: "string"
+  
+  /**
+   * The extending format for the previously mentioned type. 
+   * See Swagger 2.0 Data Type Formats for further details.
+   * 
+   * Formats provide additional semantic information about the data type,
+   * enabling more precise validation and better tooling support. Swagger 2.0
+   * defines several standard formats, but custom formats are also allowed.
+   * 
+   * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats}
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   * @example "uuid"
+   */
+  format?: string
+  
+  /**
+   * A short description of the schema. GFM syntax can be used for rich text representation.
+   * 
+   * This description should provide clear information about what the schema
+   * represents and how it should be used. It's commonly displayed in API
+   * documentation and code generation tools.
+   * 
+   * @example "A user object containing basic information"
+   * @example "Email address in RFC 5322 format"
+   */
+  description?: string
+  
+  /**
+   * A short title for the schema.
+   * 
+   * The title provides a human-readable name for the schema, often used
+   * in documentation and UI displays. It should be concise but descriptive.
+   * 
+   * @example "User"
+   * @example "Pet"
+   * @example "Order"
+   */
+  title?: string
+  
+  /**
+   * Declares the value of the schema that the server will use if none is provided.
+   * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object.
+   * 
+   * This is a Swagger 2.0 specific requirement that differs from JSON Schema.
+   * The default value must be valid according to the schema's type and constraints.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   * @example { name: "John", age: 30 }
+   * @example ["item1", "item2"]
+   */
+  default?: unknown
+  
+  /**
+   * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum}
+   * 
+   * @example ["option1", "option2", "option3"]
+   * @example ["red", "green", "blue"]
+   * @example [1, 2, 3, 4, 5]
+   */
+  enum?: unknown[]
+  
+  /**
+   * A free-form property to include an example of an instance for this schema.
+   * 
+   * Examples help developers understand how to use the schema and what kind
+   * of data is expected. They are commonly used by documentation generators
+   * and API testing tools.
+   * 
+   * @example { name: "Puma", id: 1 }
+   * @example "example string value"
+   * @example 42
+   * @example ["item1", "item2"]
+   */
+  example?: unknown
+  
+  /**
+   * A string is valid against "maxLength" if its length is less than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 | JSON Schema Validation - maxLength}
+   * 
+   * @example 100
+   * @example 255
+   */
+  maxLength?: number
+  
+  /**
+   * A string is valid against "minLength" if its length is greater than or equal to this value.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 | JSON Schema Validation - minLength}
+   * 
+   * @example 1
+   * @example 8
+   */
+  minLength?: number
+  
+  /**
+   * A string is valid against "pattern" if the regular expression matches the string successfully.
+   * The regular expression syntax follows ECMA 262.
+   * 
+   * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 | JSON Schema Validation - pattern}
+   * @see {@link https://www.ecma-international.org/ecma-262/5.1/#sec-15.10 | ECMA 262 Regular Expression Syntax}
+   * 
+   * @example "^[a-zA-Z0-9]+$"
+   * @example "^\\d{4}-\\d{2}-\\d{2}$"
+   */
+  pattern?: string
+}

versions/2.0.0/example.ts

@@ -0,0 +1,75 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Example Object
+ * -----
+ *
+ * Allows sharing examples for operation responses. Examples provide concrete
+ * instances of what the API response will look like, making it easier for
+ * developers to understand the expected data structure and format.
+ *
+ * Examples are commonly used by documentation generators and API testing tools
+ * to provide realistic sample data that developers can use as a reference
+ * when implementing client applications.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#example-object | Swagger 2.0 Example Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `[mimeType]` - The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like.
+ *
+ * @note
+ * The property names correspond to MIME types that the operation can produce.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (JSON response example):
+ * ```ts
+ * const example: Example = {
+ *   "application/json": {
+ *     "name": "Puma",
+ *     "type": "Dog",
+ *     "color": "Black",
+ *     "gender": "Female",
+ *     "breed": "Mixed"
+ *   }
+ * };
+ * ```
+ *
+ * @example (XML response example):
+ * ```ts
+ * const example: Example = {
+ *   "application/xml": "<pet><name>Puma</name><type>Dog</type></pet>"
+ * };
+ * ```
+ *
+ * @example (multiple content types):
+ * ```ts
+ * const example: Example = {
+ *   "application/json": { "id": 1, "name": "John" },
+ *   "application/xml": "<user><id>1</id><name>John</name></user>"
+ * };
+ * ```
+ */
+export interface Example extends Extension {
+  /** 
+   * The name of the property MUST be one of the Operation produces values 
+   * (either implicit or inherited). The value SHOULD be an example of what 
+   * such a response would look like.
+   * 
+   * The property name corresponds to a MIME type that the operation can produce.
+   * The value should be a realistic example of the response data in that format.
+   * 
+   * @example { "application/json": { name: "Puma", type: "Dog" } }
+   * @example { "application/xml": "<pet><name>Puma</name></pet>" }
+   * @example { "text/plain": "Success" }
+   */
+  [mimeType: string]: unknown
+}

versions/2.0.0/extensions.ts

@@ -0,0 +1,115 @@
+/**
+ * -----
+ * Base Extension Type
+ * -----
+ *
+ * All Swagger objects can be extended with vendor-specific properties.
+ * Extension properties MUST begin with "x-" and can have any valid JSON value.
+ * This enables API providers to add custom functionality and metadata to their
+ * specifications without breaking compatibility with standard Swagger tools.
+ *
+ * Extensions are a powerful mechanism for adding custom features to API
+ * specifications while maintaining interoperability. They allow for:
+ * - Custom metadata and annotations
+ * - Tool-specific configuration
+ * - API versioning information
+ * - Custom validation rules
+ * - Integration with proprietary systems
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#specification-extensions | Swagger 2.0 Specification Extensions} |
+ *
+ * -----
+ * Extension Rules
+ * -----
+ *
+ * @key `x-${string}` - Vendor extensions allow adding custom properties to Swagger objects.
+ *
+ * @note
+ * - All extension property names MUST begin with "x-" followed by any valid identifier
+ * - The value can be any valid JSON value (null, primitive, array, or object)
+ * - Extensions may or may not be supported by available tooling
+ * - Tools can be extended to add support for custom extensions
+ * - Extensions should be documented and used consistently within an organization
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple extension):
+ * ```ts
+ * const simpleExtension: Extension = {
+ *   "x-internal-id": "12345"
+ * };
+ * ```
+ *
+ * @example (complex extension):
+ * ```ts
+ * const complexExtension: Extension = {
+ *   "x-custom-feature": {
+ *     enabled: true,
+ *     version: "1.0",
+ *     configuration: {
+ *       timeout: 5000,
+ *       retries: 3
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example (array extension):
+ * ```ts
+ * const arrayExtension: Extension = {
+ *   "x-tags": ["internal", "beta", "experimental"]
+ * };
+ * ```
+ *
+ * @example (boolean extension):
+ * ```ts
+ * const booleanExtension: Extension = {
+ *   "x-deprecated": true,
+ *   "x-experimental": false
+ * };
+ * ```
+ *
+ * @example (null extension):
+ * ```ts
+ * const nullExtension: Extension = {
+ *   "x-optional-field": null
+ * };
+ * ```
+ *
+ * @example (multiple extensions):
+ * ```ts
+ * const multipleExtensions: Extension = {
+ *   "x-api-version": "2.1.0",
+ *   "x-rate-limit": {
+ *     requests: 1000,
+ *     window: "1h"
+ *   },
+ *   "x-monitoring": {
+ *     enabled: true,
+ *     alerts: ["error", "warning"]
+ *   }
+ * };
+ * ```
+ */
+export type Extension = {
+  /**
+   * Vendor extensions allow adding custom properties to Swagger objects.
+   * All extension property names MUST begin with "x-" followed by any valid identifier.
+   * The value can be any valid JSON value (null, primitive, array, or object).
+   * 
+   * Extensions enable API providers to add custom functionality and metadata
+   * to their specifications without breaking compatibility with standard
+   * Swagger tools. They should be used consistently and documented properly.
+   * 
+   * @example { "x-internal-id": "12345" }
+   * @example { "x-custom-feature": { enabled: true, version: "1.0" } }
+   * @example { "x-tags": ["internal", "beta"] }
+   * @example { "x-deprecated": true }
+   * @example { "x-optional-field": null }
+   */
+  [K in `x-${string}`]: unknown
+}

versions/2.0.0/externalDocs.ts

@@ -0,0 +1,115 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * External Documentation Object
+ * -----
+ *
+ * Allows referencing an external resource for extended documentation.
+ * This object provides a way to link to additional documentation that
+ * supplements the API specification, such as detailed guides, tutorials,
+ * or reference materials.
+ *
+ * External documentation is commonly used to provide:
+ * - Detailed API guides and tutorials
+ * - SDK documentation and examples
+ * - Integration guides and best practices
+ * - Additional reference materials
+ * - Community resources and support
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 External Documentation Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `description` - A short description of the target documentation. GFM syntax can be used for rich text representation.
+ * @key `url` - The URL for the target documentation. Value MUST be in the format of a URL. This field is required.
+ *
+ * @note
+ * The `url` field is required and must be a valid URL. The `description` field
+ * is optional but recommended to provide context about the external documentation.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple external docs):
+ * ```ts
+ * const simpleDocs: ExternalDocumentation = {
+ *   description: "Find more info here",
+ *   url: "https://swagger.io"
+ * };
+ * ```
+ *
+ * @example (detailed external docs):
+ * ```ts
+ * const detailedDocs: ExternalDocumentation = {
+ *   description: "Complete API documentation with examples and tutorials",
+ *   url: "https://docs.example.com/api"
+ * };
+ * ```
+ *
+ * @example (SDK documentation):
+ * ```ts
+ * const sdkDocs: ExternalDocumentation = {
+ *   description: "SDK documentation and code examples",
+ *   url: "https://github.com/example/sdk"
+ * };
+ * ```
+ *
+ * @example (integration guide):
+ * ```ts
+ * const integrationDocs: ExternalDocumentation = {
+ *   description: "Step-by-step integration guide",
+ *   url: "https://example.com/integration-guide"
+ * };
+ * ```
+ *
+ * @example (community resources):
+ * ```ts
+ * const communityDocs: ExternalDocumentation = {
+ *   description: "Community forum and support resources",
+ *   url: "https://community.example.com/api-support"
+ * };
+ * ```
+ *
+ * @example (minimal external docs):
+ * ```ts
+ * const minimalDocs: ExternalDocumentation = {
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ */
+export interface ExternalDocumentation extends Extension {
+  /**
+   * A short description of the target documentation. GFM syntax can be used for 
+   * rich text representation.
+   * 
+   * This description provides context about what the external documentation
+   * contains and helps developers understand when and why they should
+   * reference it.
+   * 
+   * @example "Find more info here"
+   * @example "Complete API documentation with examples and tutorials"
+   * @example "SDK documentation and code examples"
+   * @example "Step-by-step integration guide"
+   */
+  description?: string
+  
+  /**
+   * The URL for the target documentation. Value MUST be in the format of a URL.
+   * This field is required.
+   * 
+   * The URL should point to a valid, accessible resource that provides
+   * additional documentation about the API or specific aspects of it.
+   * 
+   * @example "https://swagger.io"
+   * @example "https://docs.example.com/api"
+   * @example "https://github.com/example/sdk"
+   * @example "https://example.com/integration-guide"
+   */
+  url: string
+}

versions/2.0.0/index.ts

@@ -0,0 +1,107 @@
+// Centralized exports for OpenAPI 2.0 types
+// This file serves as the main entry point for all OpenAPI 2.0 type definitions
+
+// Export the main specification type
+export type { Specification } from "./spec"
+
+// Re-export all types for convenience
+export type {
+  // Core types
+  Extension,
+} from "./extensions"
+
+export type {
+  // Info types
+    Info,
+  Contact,
+  License,
+} from "./info"
+
+export type {
+  // Path types
+  PathItemObject,
+  Operation,
+  Parameter,
+  Response,
+  Header,
+  Items,
+} from "./paths"
+
+export type {
+  // Schema types
+  Schema,
+  SwaggerSchema,
+  XML,
+  Definitions,
+  ParametersDefinitions,
+  ResponsesDefinitions,
+} from "./schema"
+
+export type {
+  // Security types
+  SecurityScheme,
+  SecurityRequirement,
+  Scopes,
+  SecurityDefinitions,
+} from "./security"
+
+export type {
+  // Utility types
+  Tag,
+} from "./tags"
+
+export type {
+  ExternalDocumentation,
+} from "./external-documentation"
+
+export type {
+  Example,
+} from "./example"
+
+export type {
+  Paths,
+} from "./paths"
+
+// Re-export data types
+export type {
+  // Base schema
+  BaseSchemaProperties,
+} from "./data-types/base-schema"
+
+export type {
+  // Individual schema types
+    StringSchema,
+    NumberSchema,
+    IntegerSchema,
+    BooleanSchema,
+  FileSchema,
+    ArraySchema,
+    ObjectSchema,
+} from "./data-types"
+
+export type {
+  // XML Object
+  XMLObject,
+} from "./xml"
+
+export type {
+  // Swagger Schema with Extensions
+  SwaggerSchemaWithExtensions,
+} from "./schema"
+
+export type {
+  // References
+  BaseReference,
+  Reference,
+} from "./references"
+
+// All supporting types are now defined in their respective modules:
+// - spec.ts: Specification (main root type)
+// - info.ts: Info, Contact, License
+// - paths.ts: PathItemObject, Operation, Parameter, Response, Header, Items
+// - schema.ts: Schema, SwaggerSchema, SwaggerSchemaWithExtensions, XML, Definitions, ParametersDefinitions, ResponsesDefinitions
+// - security.ts: SecurityScheme, SecurityRequirement, Scopes, SecurityDefinitions
+// - shallow.ts: Tag, ExternalDocumentation, Reference, Example, Paths
+// - data-types/: All individual schema types
+// - xml-object.ts: XMLObject
+// - references.ts: BaseReference, Reference

versions/2.0.0/info.ts

@@ -0,0 +1,205 @@
+import type { Extension } from "./extensions"
+import type { ExternalDocumentation } from "./externalDocs"
+
+/**
+ * Info Object
+ *
+ * The object provides metadata about the API. The metadata can be used by the clients
+ * if needed, and can be presented in the Swagger-UI for convenience.
+ *
+ * @see https://swagger.io/specification/v2/#info-object
+ * @example
+ * ```typescript
+ * const info: Info = {
+ *   title: "Swagger Sample App",
+ *   description: "This is a sample server Petstore server.",
+ *   termsOfService: "http://swagger.io/terms/",
+ *   contact: {
+ *     name: "API Support",
+ *     url: "http://www.swagger.io/support",
+ *     email: "support@swagger.io"
+ *   },
+ *   license: {
+ *     name: "Apache 2.0",
+ *     url: "http://www.apache.org/licenses/LICENSE-2.0.html"
+ *   },
+ *   version: "1.0.1"
+ * }
+ * ```
+ */
+export interface Info extends Extension {
+  /** 
+   * The title of the application. This field is required.
+   * 
+   * @example "Swagger Sample App"
+   * @example "My API"
+   */
+  title: string
+  
+  /** 
+   * A short description of the application. GFM syntax can be used for rich text representation.
+   * 
+   * @example "This is a sample server Petstore server."
+   * @example "A comprehensive API for managing user data"
+   */
+  description?: string
+  
+  /** 
+   * The Terms of Service for the API.
+   * 
+   * @example "http://swagger.io/terms/"
+   * @example "https://example.com/terms"
+   */
+  termsOfService?: string
+  
+  /** 
+   * The contact information for the exposed API.
+   * 
+   * @example { name: "API Support", email: "support@example.com" }
+   */
+  contact?: Contact
+  
+  /** 
+   * The license information for the exposed API.
+   * 
+   * @example { name: "Apache 2.0", url: "http://www.apache.org/licenses/LICENSE-2.0.html" }
+   */
+  license?: License
+  
+  /** 
+   * Provides the version of the application API (not to be confused with the specification version).
+   * This field is required.
+   * 
+   * @example "1.0.1"
+   * @example "2.0.0"
+   */
+  version: string
+}
+
+/**
+ * Contact Object
+ *
+ * Contact information for the exposed API.
+ *
+ * @see https://swagger.io/specification/v2/#contact-object
+ * @example
+ * ```typescript
+ * const contact: Contact = {
+ *   name: "API Support",
+ *   url: "http://www.swagger.io/support",
+ *   email: "support@swagger.io"
+ * }
+ * ```
+ */
+export interface Contact extends Extension {
+  /** 
+   * The identifying name of the contact person/organization.
+   * 
+   * @example "API Support"
+   * @example "John Doe"
+   */
+  name?: string
+  
+  /** 
+   * The URL pointing to the contact information. MUST be in the format of a URL.
+   * 
+   * @example "http://www.swagger.io/support"
+   * @example "https://example.com/contact"
+   */
+  url?: string
+  
+  /** 
+   * The email address of the contact person/organization. MUST be in the format of an email address.
+   * 
+   * @example "support@swagger.io"
+   * @example "contact@example.com"
+   */
+  email?: string
+}
+
+/**
+ * -----
+ * License Object
+ * -----
+ *
+ * License information for the exposed API.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#license-object | Swagger 2.0 License} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Required The license name used for the API
+ * @key `url` - Optional A URL to the license used for the API
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `name` field is required. The `url` field is optional but recommended.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (MIT License):
+ * ```ts
+ * const license: License = {
+ *   name: "MIT License",
+ *   url: "https://opensource.org/license/mit/"
+ * };
+ * ```
+ *
+ * @example (Apache 2.0):
+ * ```ts
+ * const license: License = {
+ *   name: "Apache License 2.0",
+ *   url: "https://www.apache.org/licenses/LICENSE-2.0"
+ * };
+ * ```
+ *
+ * @example (custom license):
+ * ```ts
+ * const license: License = {
+ *   name: "Proprietary Foo License",
+ *   url: "https://example.com/licenses/foo-1.0"
+ * };
+ * ```
+ *
+ * @example (license without URL):
+ * ```ts
+ * const license: License = {
+ *   name: "Custom License"
+ * };
+ * ```
+ *
+ * @example (license with extensions):
+ * ```ts
+ * const license: License = {
+ *   name: "MIT License",
+ *   url: "https://opensource.org/license/mit/",
+ *   "x-custom": "value",
+ *   "x-internal": true
+ * };
+ * ```
+ */
+export interface License extends Extension {
+  /** 
+   * The license name used for the API. This field is required.
+   * 
+   * @example "MIT License"
+   * @example "Apache License 2.0"
+   * @example "Proprietary Foo License"
+   */
+  name: string
+  
+  /** 
+   * A URL to the license used for the API. MUST be in the format of a URL.
+   * 
+   * @example "https://opensource.org/license/mit/"
+   * @example "https://www.apache.org/licenses/LICENSE-2.0"
+   * @example "https://example.com/licenses/foo-1.0"
+   */
+  url?: string
+}

versions/2.0.0/paths.ts

@@ -0,0 +1,988 @@
+import type { BaseReference } from "./references"
+import type { Extension } from "./extensions"
+import type { ExternalDocumentation } from "./external-documentation"
+import type { SwaggerSchema } from "./data-types"
+
+/**
+ * Path Item Object
+ *
+ * Describes the operations available on a single path. A Path Item may be empty,
+ * due to ACL constraints. The path itself is still exposed to the documentation
+ * viewer but they will not know which operations and parameters are available.
+ *
+ * @see https://swagger.io/specification/v2/#path-item-object
+ * @example
+ * ```typescript
+ * const pathItem: PathItemObject = {
+ *   get: {
+ *     summary: "Get users",
+ *     operationId: "getUsers",
+ *     responses: {
+ *       "200": {
+ *         description: "List of users",
+ *         schema: { type: "array", items: { $ref: "#/definitions/User" } }
+ *       }
+ *     }
+ *   },
+ *   post: {
+ *     summary: "Create user",
+ *     operationId: "createUser",
+ *     parameters: [
+ *       {
+ *         name: "user",
+ *         in: "body",
+ *         schema: { $ref: "#/definitions/User" }
+ *       }
+ *     ],
+ *     responses: {
+ *       "201": {
+ *         description: "User created",
+ *         schema: { $ref: "#/definitions/User" }
+ *       }
+ *     }
+ *   },
+ *   parameters: [
+ *     {
+ *       name: "limit",
+ *       in: "query",
+ *       type: "integer",
+ *       description: "Maximum number of items to return"
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export type PathItemObject =
+  | ({
+      /** 
+       * A definition of a GET operation on this path.
+       * 
+       * @example { summary: "Get users", responses: { "200": { description: "Success" } } }
+       */
+      get?: Operation
+      
+      /** 
+       * A definition of a PUT operation on this path.
+       * 
+       * @example { summary: "Update user", responses: { "200": { description: "Success" } } }
+       */
+      put?: Operation
+      
+      /** 
+       * A definition of a POST operation on this path.
+       * 
+       * @example { summary: "Create user", responses: { "201": { description: "Created" } } }
+       */
+      post?: Operation
+      
+      /** 
+       * A definition of a DELETE operation on this path.
+       * 
+       * @example { summary: "Delete user", responses: { "204": { description: "No Content" } } }
+       */
+      delete?: Operation
+      
+      /** 
+       * A definition of an OPTIONS operation on this path.
+       * 
+       * @example { summary: "Get options", responses: { "200": { description: "Options" } } }
+       */
+      options?: Operation
+      
+      /** 
+       * A definition of a HEAD operation on this path.
+       * 
+       * @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } }
+       */
+      head?: Operation
+      
+      /** 
+       * A definition of a PATCH operation on this path.
+       * 
+       * @example { summary: "Partially update user", responses: { "200": { description: "Success" } } }
+       */
+      patch?: Operation
+      
+      /** 
+       * A list of parameters that are applicable for all the operations described 
+       * under this path. These parameters can be overridden at the operation level, 
+       * but cannot be removed there. The list MUST NOT include duplicated parameters. 
+       * A unique parameter is defined by a combination of a name and location.
+       * 
+       * @example [{ name: "limit", in: "query", type: "integer" }]
+       */
+      parameters?: Array<Parameter | BaseReference>
+    } & Extension)
+  | BaseReference
+
+/**
+ * Operation Object
+ *
+ * Describes a single API operation on a path. A unique operation is defined 
+ * by a combination of a path and an HTTP method.
+ *
+ * @see https://swagger.io/specification/v2/#operation-object
+ * @example
+ * ```typescript
+ * const operation: Operation = {
+ *   tags: ["users"],
+ *   summary: "Get user by ID",
+ *   description: "Retrieves a specific user by their unique identifier",
+ *   operationId: "getUserById",
+ *   consumes: ["application/json"],
+ *   produces: ["application/json"],
+ *   parameters: [
+ *     {
+ *       name: "id",
+ *       in: "path",
+ *       required: true,
+ *       type: "string",
+ *       description: "The user ID"
+ *     }
+ *   ],
+ *   responses: {
+ *     "200": {
+ *       description: "User found",
+ *       schema: { $ref: "#/definitions/User" }
+ *     },
+ *     "404": {
+ *       description: "User not found"
+ *     }
+ *   },
+ *   deprecated: false,
+ *   security: [{ "api_key": [] }]
+ * }
+ * ```
+ */
+export interface Operation extends Extension {
+  /** 
+   * A list of tags for API documentation control. Tags can be used for logical 
+   * grouping of operations by resources or any other qualifier.
+   * 
+   * @example ["users", "authentication"]
+   * @example ["pets"]
+   */
+  tags?: string[]
+  
+  /** 
+   * A short summary of what the operation does. For maximum readability in 
+   * swagger-ui, this field SHOULD be less than 120 characters.
+   * 
+   * @example "Get user by ID"
+   * @example "Create a new pet"
+   */
+  summary?: string
+  
+  /** 
+   * A verbose explanation of the operation behavior. GFM syntax can be used 
+   * for rich text representation.
+   * 
+   * @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information."
+   */
+  description?: string
+  
+  /** 
+   * Additional external documentation for this operation.
+   * 
+   * @example { description: "Find out more about this operation", url: "https://example.com/docs" }
+   */
+  externalDocs?: ExternalDocumentation
+  
+  /** 
+   * Unique string used to identify the operation. The id MUST be unique among 
+   * all operations described in the API. Tools and libraries MAY use the 
+   * operationId to uniquely identify an operation, therefore, it is recommended 
+   * to follow common programming naming conventions.
+   * 
+   * @example "getUserById"
+   * @example "createPet"
+   */
+  operationId?: string
+  
+  /** 
+   * A list of MIME types the operation can consume. This overrides the consumes 
+   * definition at the Swagger Object level. An empty value MAY be used to clear 
+   * the global definition. Value MUST be as described under Mime Types.
+   * 
+   * @example ["application/json"]
+   * @example ["application/xml", "application/json"]
+   */
+  consumes?: string[]
+  
+  /** 
+   * A list of MIME types the operation can produce. This overrides the produces 
+   * definition at the Swagger Object level. An empty value MAY be used to clear 
+   * the global definition. Value MUST be as described under Mime Types.
+   * 
+   * @example ["application/json"]
+   * @example ["application/xml", "application/json"]
+   */
+  produces?: string[]
+  
+  /** 
+   * A list of parameters that are applicable for this operation. If a parameter 
+   * is already defined at the Path Item, the new definition will override it 
+   * but can never remove it. The list MUST NOT include duplicated parameters. 
+   * A unique parameter is defined by a combination of a name and location.
+   * 
+   * @example [{ name: "id", in: "path", required: true, type: "string" }]
+   */
+  parameters?: Array<Parameter | BaseReference>
+  
+  /** 
+   * The list of possible responses as they are returned from executing this operation.
+   * This field MUST be present and MUST contain at least one response.
+   * 
+   * @example { "200": { description: "Success", schema: { type: "object" } } }
+   */
+  responses: Record<string, Response | BaseReference>
+  
+  /** 
+   * The transfer protocol for the operation. Values MUST be from the list: 
+   * "http", "https", "ws", "wss". The value overrides the Swagger Object 
+   * schemes definition.
+   * 
+   * @example ["https", "http"]
+   * @example ["wss"]
+   */
+  schemes?: Array<"http" | "https" | "ws" | "wss">
+  
+  /** 
+   * Declares this operation to be deprecated. Usage of the declared operation 
+   * should be refrained. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+  
+  /** 
+   * A declaration of which security schemes are applied for this operation. 
+   * The list of values describes alternative security schemes that can be used 
+   * (that is, there is a logical OR between the security requirements). 
+   * This definition overrides any declared top-level security. To remove a 
+   * top-level security declaration, an empty array can be used.
+   * 
+   * @example [{ "api_key": [] }]
+   * @example [{ "oauth2": ["read", "write"] }]
+   */
+  security?: Array<Record<string, string[]>>
+}
+
+/**
+ * Parameter Object
+ *
+ * Describes a single operation parameter. A unique parameter is defined by a 
+ * combination of a name and location.
+ *
+ * @see https://swagger.io/specification/v2/#parameter-object
+ * @example
+ * ```typescript
+ * // Query parameter
+ * const queryParam: Parameter = {
+ *   name: "limit",
+ *   in: "query",
+ *   description: "Maximum number of items to return",
+ *   required: false,
+ *   type: "integer",
+ *   format: "int32"
+ * }
+ * 
+ * // Path parameter
+ * const pathParam: Parameter = {
+ *   name: "id",
+ *   in: "path",
+ *   description: "The user ID",
+ *   required: true,
+ *   type: "string"
+ * }
+ * 
+ * // Body parameter
+ * const bodyParam: Parameter = {
+ *   name: "user",
+ *   in: "body",
+ *   description: "User object to create",
+ *   required: true,
+ *   schema: { $ref: "#/definitions/User" }
+ * }
+ * ```
+ */
+export interface Parameter extends Extension {
+  /** 
+   * The name of the parameter. Parameter names are case sensitive.
+   * - If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object
+   * - For all other cases, the name corresponds to the parameter name used by the in property
+   * 
+   * @example "id"
+   * @example "limit"
+   * @example "user"
+   */
+  name: string
+  
+  /** 
+   * The location of the parameter. Possible values are "query", "header", "path", "formData" or "body".
+   * 
+   * - **query**: Parameters that are appended to the URL. For example, in `/users?role=admin`, the role query parameter has the value admin.
+   * - **header**: Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive.
+   * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API.
+   * - **formData**: Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded or multipart/form-data is used as the content type of the request.
+   * - **body**: The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter.
+   * 
+   * @example "query"
+   * @example "path"
+   * @example "body"
+   */
+  in: "query" | "header" | "path" | "formData" | "body"
+  
+  /** 
+   * A brief description of the parameter. This could contain examples of use. 
+   * GFM syntax can be used for rich text representation.
+   * 
+   * @example "The user ID"
+   * @example "Maximum number of items to return (default: 10)"
+   */
+  description?: string
+  
+  /** 
+   * Determines whether this parameter is mandatory. If the parameter is in "path", 
+   * this property is required and its value MUST be true. Otherwise, the property 
+   * MAY be included and its default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  required?: boolean
+  
+  /** 
+   * The type of the parameter. Since the parameter is not located at the request body, 
+   * it is limited to simple types (that is, not an object). The value MUST be one of 
+   * "string", "number", "integer", "boolean", "array" or "file". If type is "file", 
+   * the consumes MUST be either "multipart/form-data", "application/x-www-form-urlencoded" 
+   * or both and the parameter MUST be in "formData".
+   * 
+   * @example "string"
+   * @example "integer"
+   * @example "array"
+   */
+  type?: string
+  
+  /** 
+   * The extending format for the previously mentioned type. See Data Type Formats 
+   * for further details.
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   */
+  format?: string
+  
+  /** 
+   * Sets the ability to pass empty-valued parameters. This is valid only for either 
+   * query or formData parameters and allows you to send a parameter with a name only 
+   * or an empty value. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  allowEmptyValue?: boolean
+  
+  /** 
+   * The schema defining the type used for the body parameter. This property is 
+   * only applicable for parameters with in: "body".
+   * 
+   * @example { $ref: "#/definitions/User" }
+   * @example { type: "object", properties: { name: { type: "string" } } }
+   */
+  schema?: SwaggerSchema
+  
+  /** 
+   * Required if type is "array". Describes the type of items in the array.
+   * 
+   * @example { type: "string" }
+   * @example { type: "integer", format: "int32" }
+   */
+  items?: Items
+  
+  /** 
+   * Determines the format of the array if type array is used. Possible values are:
+   * - csv: comma separated values foo,bar
+   * - ssv: space separated values foo bar
+   * - tsv: tab separated values foo\tbar
+   * - pipes: pipe separated values foo|bar
+   * - multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz
+   * 
+   * @default "csv"
+   * @example "multi"
+   */
+  collectionFormat?: "csv" | "ssv" | "tsv" | "pipes" | "multi"
+  
+  /** 
+   * Declares the value of the parameter that the server will use if none is provided.
+   * This value MUST conform to the defined type for this parameter.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   */
+  default?: unknown
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
+   * 
+   * @example 100
+   */
+  maximum?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
+   * 
+   * @example false
+   */
+  exclusiveMaximum?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
+   * 
+   * @example 0
+   */
+  minimum?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
+   * 
+   * @example false
+   */
+  exclusiveMinimum?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1
+   * 
+   * @example 100
+   */
+  maxLength?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2
+   * 
+   * @example 1
+   */
+  minLength?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3
+   * 
+   * @example "^[a-zA-Z0-9]+$"
+   */
+  pattern?: string
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2
+   * 
+   * @example 10
+   */
+  maxItems?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3
+   * 
+   * @example 1
+   */
+  minItems?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4
+   * 
+   * @example true
+   */
+  uniqueItems?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
+   * 
+   * @example ["option1", "option2", "option3"]
+   */
+  enum?: unknown[]
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1
+   * 
+   * @example 2
+   */
+  multipleOf?: number
+}
+
+/**
+ * Paths Object
+ *
+ * Holds the relative paths to the individual endpoints. The path is appended to the 
+ * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints.
+ *
+ * @see https://swagger.io/specification/v2/#paths-object
+ * @example
+ * ```typescript
+ * const paths: Paths = {
+ *   "/pets": {
+ *     "get": {
+ *       "description": "Returns all pets from the system that the user has access to",
+ *       "produces": ["application/json"],
+ *       "responses": {
+ *         "200": {
+ *           "description": "A list of pets.",
+ *           "schema": {
+ *             "type": "array",
+ *             "items": {
+ *               "$ref": "#/definitions/pet"
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type Paths = Record<string, PathItemObject>
+
+/**
+ * Items Object
+ *
+ * A limited subset of JSON-Schema's items object. It is used by parameter definitions 
+ * that are not located in "body".
+ *
+ * @see https://swagger.io/specification/v2/#items-object
+ * @example
+ * ```typescript
+ * const items: Items = {
+ *   type: "string",
+ *   minLength: 2
+ * }
+ * ```
+ */
+export interface Items extends Extension {
+  /** 
+   * The internal type of the array. The value MUST be one of "string", "number", 
+   * "integer", "boolean", or "array". Files and models are not allowed.
+   * 
+   * @example "string"
+   * @example "integer"
+   * @example "array"
+   */
+  type: string
+  
+  /** 
+   * The extending format for the previously mentioned type. See Data Type Formats 
+   * for further details.
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   */
+  format?: string
+  
+  /** 
+   * Required if type is "array". Describes the type of items in the array.
+   * 
+   * @example { type: "string" }
+   * @example { type: "integer", format: "int32" }
+   */
+  items?: Items
+  
+  /** 
+   * Determines the format of the array if type array is used. Possible values are:
+   * - csv: comma separated values foo,bar
+   * - ssv: space separated values foo bar
+   * - tsv: tab separated values foo\tbar
+   * - pipes: pipe separated values foo|bar
+   * 
+   * @default "csv"
+   * @example "multi"
+   */
+  collectionFormat?: "csv" | "ssv" | "tsv" | "pipes"
+  
+  /** 
+   * Declares the value of the item that the server will use if none is provided.
+   * This value MUST conform to the defined type for the data type.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   */
+  default?: unknown
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
+   * 
+   * @example 100
+   */
+  maximum?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
+   * 
+   * @example false
+   */
+  exclusiveMaximum?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
+   * 
+   * @example 0
+   */
+  minimum?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
+   * 
+   * @example false
+   */
+  exclusiveMinimum?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1
+   * 
+   * @example 100
+   */
+  maxLength?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2
+   * 
+   * @example 1
+   */
+  minLength?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3
+   * 
+   * @example "^[a-zA-Z0-9]+$"
+   */
+  pattern?: string
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2
+   * 
+   * @example 10
+   */
+  maxItems?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3
+   * 
+   * @example 1
+   */
+  minItems?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4
+   * 
+   * @example true
+   */
+  uniqueItems?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
+   * 
+   * @example ["option1", "option2", "option3"]
+   */
+  enum?: unknown[]
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1
+   * 
+   * @example 2
+   */
+  multipleOf?: number
+}
+
+/**
+ * Paths Object
+ *
+ * Holds the relative paths to the individual endpoints. The path is appended to the 
+ * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints.
+ *
+ * @see https://swagger.io/specification/v2/#paths-object
+ * @example
+ * ```typescript
+ * const paths: Paths = {
+ *   "/pets": {
+ *     "get": {
+ *       "description": "Returns all pets from the system that the user has access to",
+ *       "produces": ["application/json"],
+ *       "responses": {
+ *         "200": {
+ *           "description": "A list of pets.",
+ *           "schema": {
+ *             "type": "array",
+ *             "items": {
+ *               "$ref": "#/definitions/pet"
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Response Object
+ *
+ * Describes a single response from an API Operation. A container for the expected 
+ * responses of an operation. The container maps a HTTP response code to the expected 
+ * response. It is not expected from the documentation to necessarily cover all 
+ * possible HTTP response codes because they may not be known in advance. However, 
+ * it is expected from the documentation to cover a successful operation response 
+ * and any known errors.
+ *
+ * @see https://swagger.io/specification/v2/#response-object
+ * @example
+ * ```typescript
+ * const response: Response = {
+ *   description: "User successfully retrieved",
+ *   schema: { $ref: "#/definitions/User" },
+ *   headers: {
+ *     "X-RateLimit-Limit": {
+ *       type: "integer",
+ *       description: "Rate limit for the current period"
+ *     }
+ *   },
+ *   examples: {
+ *     "application/json": {
+ *       id: 1,
+ *       name: "John Doe",
+ *       email: "john@example.com"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface Response extends Extension {
+  /** 
+   * A short description of the response. GFM syntax can be used for rich text representation.
+   * This field is required.
+   * 
+   * @example "User successfully retrieved"
+   * @example "Bad request - invalid input parameters"
+   * @example "Internal server error"
+   */
+  description: string
+  
+  /** 
+   * A definition of the response structure. It can be a primitive, an array or an object. 
+   * If this field does not exist, it means no content is returned as part of the response. 
+   * As an extension to the Schema Object, its root type value may also be "file". 
+   * This SHOULD be accompanied by a relevant produces mime-type.
+   * 
+   * @example { $ref: "#/definitions/User" }
+   * @example { type: "array", items: { $ref: "#/definitions/User" } }
+   * @example { type: "string" }
+   */
+  schema?: SwaggerSchema
+  
+  /** 
+   * A list of headers that are sent with the response.
+   * 
+   * @example { "X-RateLimit-Limit": { type: "integer", description: "Rate limit" } }
+   */
+  headers?: Record<string, Header>
+  
+  /** 
+   * An example of the response message. This property is not part of the OpenAPI 
+   * specification but is commonly used by tools to provide example responses.
+   * 
+   * @example { "application/json": { id: 1, name: "John Doe" } }
+   */
+  examples?: Record<string, unknown>
+}
+
+/**
+ * Header Object
+ *
+ * Describes a single header parameter. A list of all headers that are sent with 
+ * the response. The name is used to refer to the respective header definition. 
+ * The value of the header is of type string.
+ *
+ * @see https://swagger.io/specification/v2/#header-object
+ * @example
+ * ```typescript
+ * const header: Header = {
+ *   description: "Rate limit for the current period",
+ *   type: "integer",
+ *   format: "int32"
+ * }
+ * ```
+ */
+export interface Header extends Extension {
+  /** 
+   * A brief description of the header. GFM syntax can be used for rich text representation.
+   * 
+   * @example "Rate limit for the current period"
+   * @example "Content type of the response"
+   */
+  description?: string
+  
+  /** 
+   * The type of the object. The value MUST be one of "string", "number", "integer", 
+   * "boolean", or "array".
+   * This field is required.
+   * 
+   * @example "string"
+   * @example "integer"
+   * @example "array"
+   */
+  type: string
+  
+  /** 
+   * The extending format for the previously mentioned type. See Data Type Formats 
+   * for further details.
+   * 
+   * @example "int32"
+   * @example "date"
+   * @example "email"
+   */
+  format?: string
+  
+  /** 
+   * Required if type is "array". Describes the type of items in the array.
+   * 
+   * @example { type: "string" }
+   * @example { type: "integer", format: "int32" }
+   */
+  items?: Items
+  
+  /** 
+   * Determines the format of the array if type array is used. Possible values are:
+   * - csv: comma separated values foo,bar
+   * - ssv: space separated values foo bar
+   * - tsv: tab separated values foo\tbar
+   * - pipes: pipe separated values foo|bar
+   * 
+   * @default "csv"
+   * @example "multi"
+   */
+  collectionFormat?: "csv" | "ssv" | "tsv" | "pipes"
+  
+  /** 
+   * Declares the value of the header that the server will use if none is provided.
+   * This value MUST conform to the defined type for the header.
+   * 
+   * @example "defaultValue"
+   * @example 10
+   */
+  default?: unknown
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
+   * 
+   * @example 100
+   */
+  maximum?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2
+   * 
+   * @example false
+   */
+  exclusiveMaximum?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
+   * 
+   * @example 0
+   */
+  minimum?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3
+   * 
+   * @example false
+   */
+  exclusiveMinimum?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1
+   * 
+   * @example 100
+   */
+  maxLength?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2
+   * 
+   * @example 1
+   */
+  minLength?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3
+   * 
+   * @example "^[a-zA-Z0-9]+$"
+   */
+  pattern?: string
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2
+   * 
+   * @example 10
+   */
+  maxItems?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3
+   * 
+   * @example 1
+   */
+  minItems?: number
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4
+   * 
+   * @example true
+   */
+  uniqueItems?: boolean
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
+   * 
+   * @example ["option1", "option2", "option3"]
+   */
+  enum?: unknown[]
+  
+  /** 
+   * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1
+   * 
+   * @example 2
+   */
+  multipleOf?: number
+}
+
+/**
+ * Paths Object
+ *
+ * Holds the relative paths to the individual endpoints. The path is appended to the 
+ * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints.
+ *
+ * @see https://swagger.io/specification/v2/#paths-object
+ * @example
+ * ```typescript
+ * const paths: Paths = {
+ *   "/pets": {
+ *     "get": {
+ *       "description": "Returns all pets from the system that the user has access to",
+ *       "produces": ["application/json"],
+ *       "responses": {
+ *         "200": {
+ *           "description": "A list of pets.",
+ *           "schema": {
+ *             "type": "array",
+ *             "items": {
+ *               "$ref": "#/definitions/pet"
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type Paths = Record<string, PathItemObject>

versions/2.0.0/references.ts

@@ -0,0 +1,132 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * JSON Reference Object
+ * -----
+ *
+ * A simple object to allow referencing other definitions in the specification.
+ * It can be used to reference parameters and responses that are defined at the 
+ * top level for reuse. The Reference Object is a JSON Reference that uses a 
+ * JSON Pointer as its value. For this specification, only canonical dereferencing 
+ * is supported.
+ *
+ * JSON References enable reusability and modularity in API specifications by
+ * allowing the same definition to be referenced multiple times throughout the
+ * document. This reduces duplication and makes specifications easier to maintain.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#reference-object | Swagger 2.0 Reference Object} |
+ * | 2.0     | {@link https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02 | JSON Reference Specification} |
+ * | 2.0     | {@link https://tools.ietf.org/html/rfc6901 | JSON Pointer Specification} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `$ref` - The reference string. This field is required.
+ *
+ * @note
+ * The reference string follows JSON Pointer syntax and can reference:
+ * - Definitions within the same document using "#/definitions/Name"
+ * - Parameters within the same document using "#/parameters/Name"
+ * - Responses within the same document using "#/responses/Name"
+ * - External files using relative or absolute URLs
+ * - Specific parts of external files using fragment identifiers
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (definition reference):
+ * ```ts
+ * const userRef: BaseReference = {
+ *   $ref: "#/definitions/User"
+ * };
+ * ```
+ *
+ * @example (parameter reference):
+ * ```ts
+ * const pageParamRef: BaseReference = {
+ *   $ref: "#/parameters/PageParam"
+ * };
+ * ```
+ *
+ * @example (response reference):
+ * ```ts
+ * const notFoundRef: BaseReference = {
+ *   $ref: "#/responses/NotFound"
+ * };
+ * ```
+ *
+ * @example (external file reference):
+ * ```ts
+ * const externalRef: BaseReference = {
+ *   $ref: "Pet.json"
+ * };
+ * ```
+ *
+ * @example (external file with fragment):
+ * ```ts
+ * const externalFragmentRef: BaseReference = {
+ *   $ref: "definitions.json#/Pet"
+ * };
+ * ```
+ *
+ * @example (absolute URL reference):
+ * ```ts
+ * const absoluteRef: BaseReference = {
+ *   $ref: "https://api.example.com/schemas/User.json"
+ * };
+ * ```
+ */
+export interface BaseReference {
+  /**
+   * The reference string. This field is required.
+   * 
+   * The reference string follows JSON Pointer syntax and can reference:
+   * - Definitions within the same document using "#/definitions/Name"
+   * - Parameters within the same document using "#/parameters/Name"  
+   * - Responses within the same document using "#/responses/Name"
+   * - External files using relative or absolute URLs
+   * - Specific parts of external files using fragment identifiers
+   * 
+   * @example "#/definitions/Pet"
+   * @example "#/parameters/skipParam"
+   * @example "#/responses/NotFound"
+   * @example "Pet.json"
+   * @example "definitions.json#/Pet"
+   * @example "https://api.example.com/schemas/User.json"
+   */
+  $ref: string
+}
+
+/**
+ * -----
+ * Reference Object with Extensions
+ * -----
+ *
+ * A reference object that can be extended with vendor-specific properties.
+ * This allows for additional metadata to be attached to references while
+ * maintaining the core reference functionality.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#reference-object | Swagger 2.0 Reference Object} |
+ * | 2.0     | {@link https://swagger.io/specification/v2/#specification-extensions | Swagger 2.0 Extensions} |
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (reference with extensions):
+ * ```ts
+ * const extendedRef: Reference = {
+ *   $ref: "#/definitions/User",
+ *   "x-deprecated": true,
+ *   "x-version": "1.0.0"
+ * };
+ * ```
+ */
+export interface Reference extends BaseReference, Extension {}

versions/2.0.0/schema.ts

@@ -0,0 +1,378 @@
+import type {
+  StringSchema,
+  NumberSchema,
+  IntegerSchema,
+  BooleanSchema,
+  ArraySchema,
+  ObjectSchema,
+  FileSchema,
+  SwaggerSchema as BaseSwaggerSchema,
+  BaseSchemaProperties,
+} from "./data-types"
+import type { BaseReference } from "./references"
+import type { XMLObject } from "./xml"
+import type { ExternalDocumentation } from "./externalDocs"
+
+/**
+ * Schema Object (Swagger 2.0)
+ *
+ * The Schema Object allows the definition of input and output data types.
+ * These types can be objects, but also primitives and arrays. This object
+ * is a subset of JSON Schema Specification Draft 4 and uses the same
+ * formatting rules (sections 9-11).
+ *
+ * In Swagger 2.0, this is a limited subset of JSON Schema. Here we model it
+ * as a union of known schema atoms or a reference to a definition.
+ *
+ * @see https://swagger.io/specification/v2/#schema-object
+ * @example
+ * ```typescript
+ * // String schema
+ * const stringSchema: Schema = {
+ *   type: "string",
+ *   minLength: 1,
+ *   maxLength: 100
+ * }
+ * 
+ * // Object schema
+ * const objectSchema: Schema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "integer" }
+ *   },
+ *   required: ["name"]
+ * }
+ * 
+ * // Reference to a definition
+ * const refSchema: Schema = {
+ *   $ref: "#/definitions/User"
+ * }
+ * ```
+ */
+export type Schema = BaseSwaggerSchema
+
+/**
+ * XML Object
+ *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms) 
+ * and the name property should be used to add that information.
+ *
+ * @see https://swagger.io/specification/v2/#xml-object
+ * @example
+ * ```typescript
+ * const xml: XML = {
+ *   name: "animal",
+ *   namespace: "http://example.com/schema/sample",
+ *   prefix: "sample",
+ *   attribute: false,
+ *   wrapped: true
+ * }
+ * ```
+ */
+/**
+ * -----
+ * Swagger Schema with Extensions
+ * -----
+ *
+ * Extended schema that includes Swagger 2.0 specific properties beyond JSON Schema.
+ * This interface combines the base schema properties with Swagger-specific extensions
+ * that provide additional functionality for API documentation and validation.
+ *
+ * Swagger 2.0 extends JSON Schema with several additional properties that are
+ * specific to API documentation needs, including polymorphism support, read-only
+ * properties, XML representation metadata, and external documentation references.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `discriminator` - Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema.
+ * @key `readOnly` - Relevant only for Schema "properties" definitions. Declares the property as "read only".
+ * @key `xml` - This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
+ * @key `externalDocs` - Additional external documentation for this schema.
+ *
+ * @note
+ * All Swagger-specific extension fields are optional. The `discriminator` field
+ * is used for polymorphism and must be defined in the schema and included in
+ * the required property list when used.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (schema with discriminator):
+ * ```ts
+ * const polymorphicSchema: SwaggerSchemaWithExtensions = {
+ *   type: "object",
+ *   discriminator: "petType",
+ *   properties: {
+ *     name: { type: "string" },
+ *     petType: { type: "string" }
+ *   },
+ *   required: ["name", "petType"]
+ * };
+ * ```
+ *
+ * @example (read-only property):
+ * ```ts
+ * const readOnlySchema: SwaggerSchemaWithExtensions = {
+ *   type: "object",
+ *   properties: {
+ *     id: { type: "integer", readOnly: true },
+ *     name: { type: "string" },
+ *     createdAt: { type: "string", format: "date-time", readOnly: true }
+ *   },
+ *   required: ["name"]
+ * };
+ * ```
+ *
+ * @example (schema with XML metadata):
+ * ```ts
+ * const xmlSchema: SwaggerSchemaWithExtensions = {
+ *   type: "object",
+ *   properties: {
+ *     id: { 
+ *       type: "integer",
+ *       xml: { attribute: true }
+ *     },
+ *     name: { 
+ *       type: "string",
+ *       xml: { 
+ *         name: "personName",
+ *         namespace: "http://example.com/schema",
+ *         prefix: "ex"
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example (schema with external docs):
+ * ```ts
+ * const documentedSchema: SwaggerSchemaWithExtensions = {
+ *   type: "object",
+ *   properties: {
+ *     data: { type: "string" }
+ *   },
+ *   externalDocs: {
+ *     description: "Find out more about this schema",
+ *     url: "https://example.com/docs/schema"
+ *   }
+ * };
+ * ```
+ *
+ * @example (complete schema with all extensions):
+ * ```ts
+ * const completeSchema: SwaggerSchemaWithExtensions = {
+ *   type: "object",
+ *   discriminator: "type",
+ *   properties: {
+ *     id: { type: "integer", readOnly: true },
+ *     type: { type: "string" },
+ *     data: { 
+ *       type: "string",
+ *       xml: { name: "content" }
+ *     }
+ *   },
+ *   required: ["type"],
+ *   externalDocs: {
+ *     description: "Complete schema documentation",
+ *     url: "https://docs.example.com/schema"
+ *   }
+ * };
+ * ```
+ */
+export interface SwaggerSchemaWithExtensions extends BaseSchemaProperties {
+  // String-specific properties
+  maxLength?: number
+  minLength?: number
+  pattern?: string
+  
+  // Number/Integer-specific properties
+  multipleOf?: number
+  maximum?: number
+  exclusiveMaximum?: boolean
+  minimum?: number
+  exclusiveMinimum?: boolean
+  
+  // Array-specific properties
+  items?: SwaggerSchema | BaseReference
+  maxItems?: number
+  minItems?: number
+  uniqueItems?: boolean
+  
+  // Object-specific properties
+  properties?: Record<string, SwaggerSchema | BaseReference>
+  required?: string[]
+  additionalProperties?: boolean | SwaggerSchema | BaseReference
+  allOf?: (SwaggerSchema | BaseReference)[]
+  maxProperties?: number
+  minProperties?: number
+  
+  // Swagger-specific extensions
+  /**
+   * Adds support for polymorphism. The discriminator is the schema property name 
+   * that is used to differentiate between other schema that inherit this schema. 
+   * The property name used MUST be defined at this schema and it MUST be in the 
+   * required property list. When used, the value MUST be the name of this schema 
+   * or any schema that inherits it.
+   * 
+   * @example "petType"
+   * @example "type"
+   * @example "category"
+   */
+  discriminator?: string
+  
+  /**
+   * Relevant only for Schema "properties" definitions. Declares the property as "read only". 
+   * This means that it MAY be sent as part of a response but MUST NOT be sent as part 
+   * of the request. Properties marked as readOnly being true SHOULD NOT be in the 
+   * required list of the defined schema. Default value is false.
+   * 
+   * @default false
+   * @example true
+   * @example false
+   */
+  readOnly?: boolean
+  
+  /**
+   * This MAY be used only on properties schemas. It has no effect on root schemas. 
+   * Adds Additional metadata to describe the XML representation format of this property.
+   * 
+   * @example { name: "animal", wrapped: true }
+   * @example { attribute: true }
+   * @example { namespace: "http://example.com/schema", prefix: "ex" }
+   */
+  xml?: XMLObject
+  
+  /**
+   * Additional external documentation for this schema.
+   * 
+   * @example { description: "Find out more about this schema", url: "https://example.com/docs" }
+   * @example { description: "Schema reference guide", url: "https://docs.example.com/schema" }
+   */
+  externalDocs?: ExternalDocumentation
+}
+
+/**
+ * Extended Schema Object that includes Swagger 2.0 specific properties
+ * This combines the base Schema types with Swagger-specific extensions
+ */
+export type SwaggerSchema = SwaggerSchemaWithExtensions
+
+/**
+ * XML Object
+ * 
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms) 
+ * and the name property should be used to add that information.
+ * 
+ * @see https://swagger.io/specification/v2/#xml-object
+ */
+export type XML = XMLObject
+
+/**
+ * Definitions Object
+ *
+ * An object to hold data types that can be consumed and produced by operations. 
+ * These data types can be primitives, arrays or models.
+ *
+ * @see https://swagger.io/specification/v2/#definitions-object
+ * @example
+ * ```typescript
+ * const definitions: Definitions = {
+ *   "Category": {
+ *     "type": "object",
+ *     "properties": {
+ *       "id": {
+ *         "type": "integer",
+ *         "format": "int64"
+ *       },
+ *       "name": {
+ *         "type": "string"
+ *       }
+ *     }
+ *   },
+ *   "Tag": {
+ *     "type": "object",
+ *     "properties": {
+ *       "id": {
+ *         "type": "integer",
+ *         "format": "int64"
+ *       },
+ *       "name": {
+ *         "type": "string"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type Definitions = Record<string, SwaggerSchema>
+
+/**
+ * Parameters Definitions Object
+ *
+ * An object to hold parameters to be reused across operations. Parameter definitions 
+ * can be referenced to the ones defined here. This does not define global operation parameters.
+ *
+ * @see https://swagger.io/specification/v2/#parameters-definitions-object
+ * @example
+ * ```typescript
+ * const parameters: ParametersDefinitions = {
+ *   "skipParam": {
+ *     "name": "skip",
+ *     "in": "query",
+ *     "description": "number of items to skip",
+ *     "required": true,
+ *     "type": "integer",
+ *     "format": "int32"
+ *   },
+ *   "limitParam": {
+ *     "name": "limit",
+ *     "in": "query",
+ *     "description": "max records to return",
+ *     "required": true,
+ *     "type": "integer",
+ *     "format": "int32"
+ *   }
+ * }
+ * ```
+ */
+export type ParametersDefinitions = Record<string, Parameter | BaseReference>
+
+/**
+ * Responses Definitions Object
+ *
+ * An object to hold responses to be reused across operations. Response definitions 
+ * can be referenced to the ones defined here. This does not define global operation responses.
+ *
+ * @see https://swagger.io/specification/v2/#responses-definitions-object
+ * @example
+ * ```typescript
+ * const responses: ResponsesDefinitions = {
+ *   "NotFound": {
+ *     "description": "Entity not found."
+ *   },
+ *   "IllegalInput": {
+ *     "description": "Illegal input for operation."
+ *   },
+ *   "GeneralError": {
+ *     "description": "General Error",
+ *     "schema": {
+ *       "$ref": "#/definitions/GeneralError"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type ResponsesDefinitions = Record<string, Response | BaseReference>
+
+// Re-export types from paths.ts to avoid circular dependencies
+import type { Parameter, Response } from "./paths"

versions/2.0.0/security.ts

@@ -0,0 +1,216 @@
+import type { Extension } from "./extensions"
+
+/**
+ * Security Scheme Object
+ *
+ * Defines a security scheme that can be used by the operations. Supported schemes 
+ * are basic authentication, an API key (either as a header or as a query parameter) 
+ * and OAuth2's common flows (implicit, password, application and access code).
+ *
+ * @see https://swagger.io/specification/v2/#security-scheme-object
+ * @example
+ * ```typescript
+ * // API Key authentication
+ * const apiKeyScheme: SecurityScheme = {
+ *   type: "apiKey",
+ *   name: "X-API-Key",
+ *   in: "header",
+ *   description: "API key for authentication"
+ * }
+ * 
+ * // OAuth2 with authorization code flow
+ * const oauth2Scheme: SecurityScheme = {
+ *   type: "oauth2",
+ *   flow: "accessCode",
+ *   authorizationUrl: "https://example.com/oauth/authorize",
+ *   tokenUrl: "https://example.com/oauth/token",
+ *   scopes: {
+ *     "read": "Read access to resources",
+ *     "write": "Write access to resources"
+ *   }
+ * }
+ * 
+ * // Basic authentication
+ * const basicScheme: SecurityScheme = {
+ *   type: "basic",
+ *   description: "HTTP Basic Authentication"
+ * }
+ * ```
+ */
+export interface SecurityScheme extends Extension {
+  /** 
+   * The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
+   * This field is required.
+   * 
+   * - **basic**: Basic HTTP authentication
+   * - **apiKey**: API key authentication (header or query parameter)
+   * - **oauth2**: OAuth 2.0 authentication
+   * 
+   * @example "apiKey"
+   * @example "oauth2"
+   * @example "basic"
+   */
+  type: "basic" | "apiKey" | "oauth2"
+  
+  /** 
+   * A short description for security scheme. GFM syntax can be used for rich text representation.
+   * 
+   * @example "API key for authentication"
+   * @example "OAuth 2.0 with authorization code flow"
+   */
+  description?: string
+  
+  /** 
+   * The name of the header or query parameter to be used. This field is required 
+   * for apiKey type and applies to apiKey type only.
+   * 
+   * @example "X-API-Key"
+   * @example "Authorization"
+   */
+  name?: string
+  
+  /** 
+   * The location of the API key. This field is required for apiKey type and 
+   * applies to apiKey type only. Valid values are "query" or "header".
+   * 
+   * @example "header"
+   * @example "query"
+   */
+  in?: "query" | "header"
+  
+  /** 
+   * The flow used by the OAuth2 security scheme. This field is required for 
+   * oauth2 type and applies to oauth2 type only. Valid values are "implicit", 
+   * "password", "application" or "accessCode".
+   * 
+   * - **implicit**: Implicit flow
+   * - **password**: Resource owner password credentials flow
+   * - **application**: Client credentials flow
+   * - **accessCode**: Authorization code flow
+   * 
+   * @example "accessCode"
+   * @example "implicit"
+   * @example "password"
+   */
+  flow?: "implicit" | "password" | "application" | "accessCode"
+  
+  /** 
+   * The authorization URL to be used for this flow. This SHOULD be in the form of 
+   * a URL. This field is required for oauth2 type and applies to oauth2 type only.
+   * 
+   * @example "https://example.com/oauth/authorize"
+   * @example "https://api.example.com/oauth/authorize"
+   */
+  authorizationUrl?: string
+  
+  /** 
+   * The token URL to be used for this flow. This SHOULD be in the form of a URL. 
+   * This field is required for oauth2 type and applies to oauth2 type only.
+   * 
+   * @example "https://example.com/oauth/token"
+   * @example "https://api.example.com/oauth/token"
+   */
+  tokenUrl?: string
+  
+  /** 
+   * The available scopes for the OAuth2 security scheme. The key is the scope name 
+   * and the value is a short description of the scope. This field is required for 
+   * oauth2 type and applies to oauth2 type only.
+   * 
+   * @example { "read": "Read access to resources", "write": "Write access to resources" }
+   * @example { "admin": "Administrative access" }
+   */
+  scopes?: Scopes
+}
+
+/**
+ * Scopes Object
+ *
+ * Lists the available scopes for an OAuth2 security scheme.
+ *
+ * @see https://swagger.io/specification/v2/#scopes-object
+ * @example
+ * ```typescript
+ * const scopes: Scopes = {
+ *   "write:pets": "modify pets in your account",
+ *   "read:pets": "read your pets"
+ * }
+ * ```
+ */
+export interface Scopes {
+  /** 
+   * Maps between a name of a scope to a short description of it (as the value of the property).
+   * The key is the scope name and the value is a short description of the scope.
+   * 
+   * @example { "read": "Read access to resources", "write": "Write access to resources" }
+   * @example { "admin": "Administrative access" }
+   */
+  [scopeName: string]: string
+}
+
+/**
+ * Security Requirement Object
+ *
+ * Lists the required security schemes to execute this operation. The object can have 
+ * multiple security schemes declared in it which are all required (that is, there is 
+ * a logical AND between the schemes). The name used for each property MUST correspond 
+ * to a security scheme declared in the Security Definitions.
+ *
+ * @see https://swagger.io/specification/v2/#security-requirement-object
+ * @example
+ * ```typescript
+ * // Non-OAuth2 Security Requirement
+ * const nonOAuth2Security: SecurityRequirement = {
+ *   "api_key": []
+ * }
+ * 
+ * // OAuth2 Security Requirement
+ * const oauth2Security: SecurityRequirement = {
+ *   "petstore_auth": [
+ *     "write:pets",
+ *     "read:pets"
+ *   ]
+ * }
+ * ```
+ */
+export interface SecurityRequirement {
+  /** 
+   * Each name must correspond to a security scheme which is declared in the Security Definitions. 
+   * If the security scheme is of type "oauth2", then the value is a list of scope names 
+   * required for the execution. For other security scheme types, the array MUST be empty.
+   * 
+   * @example { "api_key": [] }
+   * @example { "oauth2": ["read", "write"] }
+   */
+  [schemeName: string]: string[]
+}
+
+/**
+ * Security Definitions Object
+ *
+ * A declaration of the security schemes available to be used in the specification. 
+ * This does not enforce the security schemes on the operations and only serves to 
+ * provide the relevant details for each scheme.
+ *
+ * @see https://swagger.io/specification/v2/#security-definitions-object
+ * @example
+ * ```typescript
+ * const securityDefinitions: SecurityDefinitions = {
+ *   "api_key": {
+ *     "type": "apiKey",
+ *     "name": "api_key",
+ *     "in": "header"
+ *   },
+ *   "petstore_auth": {
+ *     "type": "oauth2",
+ *     "authorizationUrl": "http://swagger.io/api/oauth/dialog",
+ *     "flow": "implicit",
+ *     "scopes": {
+ *       "write:pets": "modify pets in your account",
+ *       "read:pets": "read your pets"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type SecurityDefinitions = Record<string, SecurityScheme>

versions/2.0.0/spec.ts

@@ -0,0 +1,225 @@
+import type { Extension } from "./extensions"
+
+// Import all the major component types
+import type { Info } from "./info"
+import type { 
+  PathItemObject, 
+  Operation, 
+  Parameter, 
+  Response, 
+  Header, 
+  Items 
+} from "./paths"
+import type { 
+  Schema, 
+  SwaggerSchema, 
+  XML, 
+  Definitions, 
+  ParametersDefinitions, 
+  ResponsesDefinitions 
+} from "./schema"
+import type { 
+  SecurityScheme, 
+  SecurityRequirement, 
+  Scopes, 
+  SecurityDefinitions 
+} from "./security"
+import type { Tag } from "./tags"
+import type { ExternalDocumentation } from "./external-documentation"
+import type { Reference } from "./references"
+import type { Example } from "./example"
+import type { Paths } from "./paths"
+
+/**
+ * Root Swagger 2.0 Schema (Swagger Object)
+ * 
+ * This is the root document object of the OpenAPI specification. It contains
+ * all the metadata about the API being described. This object is based on the
+ * JSON Schema Specification Draft 4 and uses a predefined subset of it.
+ * 
+ * The Swagger Object is the root of the specification document and contains
+ * all the information about the API, including its metadata, available paths,
+ * data models, security schemes, and more.
+ * 
+ * @see https://swagger.io/specification/v2/#swagger-object
+ * @example
+ * ```typescript
+ * const swagger: Specification = {
+ *   swagger: "2.0",
+ *   info: {
+ *     title: "Swagger Sample App",
+ *     description: "This is a sample server Petstore server.",
+ *     version: "1.0.1"
+ *   },
+ *   host: "petstore.swagger.io",
+ *   basePath: "/v2",
+ *   schemes: ["https"],
+ *   paths: {
+ *     "/pets": {
+ *       get: {
+ *         summary: "List all pets",
+ *         responses: {
+ *           "200": {
+ *             description: "A list of pets",
+ *             schema: {
+ *               type: "array",
+ *               items: { $ref: "#/definitions/Pet" }
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   definitions: {
+ *     Pet: {
+ *       type: "object",
+ *       properties: {
+ *         id: { type: "integer", format: "int64" },
+ *         name: { type: "string" },
+ *         tag: { type: "string" }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type Specification = {
+  /** 
+   * Specifies the Swagger specification version being used. 
+   * Must be "2.0" for this specification.
+   */
+  swagger: "2.0"
+  
+  /** 
+   * Provides metadata about the API. The metadata can be used by the clients 
+   * if needed, and can be presented in the Swagger-UI for convenience.
+   */
+  info: Info
+  
+  /** 
+   * The host (name or IP) serving the API. This MUST be the host only and does 
+   * not include the scheme nor sub-paths. It MAY include a port. If the host 
+   * is not included, the host serving the documentation is to be used 
+   * (including the port). The host does not support path templating.
+   * 
+   * @example "api.example.com"
+   * @example "api.example.com:8080"
+   */
+  host?: string
+  
+  /** 
+   * The base path on which the API is served, which is relative to the host. 
+   * If it is not included, the API is served directly under the host. 
+   * The value MUST start with a leading slash (/). The basePath does not 
+   * support path templating.
+   * 
+   * @example "/v1"
+   * @example "/api/v2"
+   */
+  basePath?: string
+  
+  /** 
+   * The transfer protocol of the API. Values MUST be from the list: 
+   * "http", "https", "ws", "wss". If the schemes is not included, the default 
+   * scheme to be used is the one used to access the specification.
+   * 
+   * @example ["https", "http"]
+   * @example ["wss"]
+   */
+  schemes?: Array<"http" | "https" | "ws" | "wss">
+  
+  /** 
+   * A list of MIME types the APIs can consume. This is global to all APIs 
+   * but can be overridden on specific API calls. Value MUST be as described 
+   * under Mime Types.
+   * 
+   * @example ["application/json"]
+   * @example ["application/xml", "application/json"]
+   */
+  consumes?: string[]
+  
+  /** 
+   * A list of MIME types the APIs can produce. This is global to all APIs 
+   * but can be overridden on specific API calls. Value MUST be as described 
+   * under Mime Types.
+   * 
+   * @example ["application/json"]
+   * @example ["application/xml", "application/json"]
+   */
+  produces?: string[]
+  
+  /** 
+   * The available paths and operations for the API. This is the root of the 
+   * Path Item Object. It does not define a path or a basePath, they are defined 
+   * in the Paths Object. A relative path to an individual endpoint. The field 
+   * name MUST begin with a slash. The path is appended to the basePath in order 
+   * to construct the full URL. Path templating is allowed.
+   * 
+   * @example { "/users": { get: { ... } } }
+   * @example { "/users/{id}": { get: { ... } } }
+   */
+  paths: Paths
+  
+  /** 
+   * An object to hold data types produced and consumed by operations. 
+   * These data types can be primitives, arrays or models.
+   * 
+   * @example { "User": { type: "object", properties: { ... } } }
+   */
+  definitions?: Definitions
+  
+  /** 
+   * An object to hold parameters that can be used across operations. 
+   * This property does not define global parameters for all operations.
+   * 
+   * @example { "pageParam": { name: "page", in: "query", type: "integer" } }
+   */
+  parameters?: ParametersDefinitions
+  
+  /** 
+   * An object to hold responses that can be used across operations. 
+   * This property does not define global responses for all operations.
+   * 
+   * @example { "NotFound": { description: "Entity not found" } }
+   */
+  responses?: ResponsesDefinitions
+  
+  /** 
+   * Security scheme definitions that can be used by the operations. 
+   * Supported schemes are basic authentication, an API key (either as a header 
+   * or as a query parameter) and OAuth2's common flows (implicit, password, 
+   * application and access code).
+   * 
+   * @example { "api_key": { type: "apiKey", in: "header", name: "X-API-Key" } }
+   */
+  securityDefinitions?: SecurityDefinitions
+  
+  /** 
+   * A declaration of which security schemes are applied for the API as a whole. 
+   * The list of values describes alternative security schemes that can be used 
+   * (that is, there is a logical OR between the security requirements). 
+   * Individual operations can override this definition.
+   * 
+   * @example [{ "api_key": [] }]
+   * @example [{ "oauth2": ["read", "write"] }]
+   */
+  security?: SecurityRequirement[]
+  
+  /** 
+   * A list of tags used by the specification with additional metadata. 
+   * The order of the tags can be used to reflect on their order by the 
+   * parsing tools. Not all tags that are used by the Operation Object must 
+   * be declared. The tags that are not declared may be organized randomly 
+   * or based on the tools' logic. Each tag name in the list MUST be unique.
+   * 
+   * @example [{ name: "users", description: "User management" }]
+   */
+  tags?: Tag[]
+  
+  /** 
+   * Additional external documentation.
+   * 
+   * @example { description: "Find out more about our API", url: "https://example.com/docs" }
+   */
+  externalDocs?: ExternalDocumentation
+} & Extension

versions/2.0.0/tags.ts

@@ -0,0 +1,127 @@
+import type { Extension } from "./extensions"
+import type { ExternalDocumentation } from "./external-documentation"
+
+/**
+ * -----
+ * Tag Object
+ * -----
+ *
+ * A grouping tag for operations. Tags can be used for logical grouping of operations 
+ * by resources or any other qualifier. The order of the tags can be used to reflect 
+ * on their order by the parsing tools. Not all tags that are used by the Operation 
+ * Object must be declared. The tags that are not declared may be organized randomly 
+ * or based on the tools' logic. Each tag name in the list MUST be unique.
+ *
+ * Tags provide a way to organize and categorize API operations, making it easier
+ * for developers to understand and navigate the API. They are commonly used to
+ * group operations by resource type, functionality, or any other logical division.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#tag-object | Swagger 2.0 Tag Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - The name of the tag. This field is required and MUST be unique.
+ * @key `description` - A short description for the tag. GFM syntax can be used for rich text representation.
+ * @key `externalDocs` - Additional external documentation for this tag.
+ *
+ * @note
+ * All fields are optional except for `name`. The `name` field must be unique
+ * within the specification and is used to reference the tag in Operation objects.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple tag):
+ * ```ts
+ * const simpleTag: Tag = {
+ *   name: "users",
+ *   description: "User management operations"
+ * };
+ * ```
+ *
+ * @example (detailed tag):
+ * ```ts
+ * const detailedTag: Tag = {
+ *   name: "authentication",
+ *   description: "Authentication and authorization operations",
+ *   externalDocs: {
+ *     description: "Find out more about our authentication system",
+ *     url: "https://example.com/docs/auth"
+ *   }
+ * };
+ * ```
+ *
+ * @example (resource tag):
+ * ```ts
+ * const resourceTag: Tag = {
+ *   name: "pets",
+ *   description: "Pet store operations including CRUD operations for pets",
+ *   externalDocs: {
+ *     description: "Pet management API documentation",
+ *     url: "https://petstore.example.com/docs"
+ *   }
+ * };
+ * ```
+ *
+ * @example (functional tag):
+ * ```ts
+ * const functionalTag: Tag = {
+ *   name: "reports",
+ *   description: "Generate and manage various reports",
+ *   externalDocs: {
+ *     description: "Report generation guide",
+ *     url: "https://docs.example.com/reports"
+ *   }
+ * };
+ * ```
+ *
+ * @example (minimal tag):
+ * ```ts
+ * const minimalTag: Tag = {
+ *   name: "admin"
+ * };
+ * ```
+ */
+export interface Tag extends Extension {
+  /**
+   * The name of the tag. This field is required and MUST be unique.
+   * 
+   * The tag name is used to reference this tag in Operation objects and
+   * must be unique within the entire specification. It should be descriptive
+   * and follow a consistent naming convention.
+   * 
+   * @example "users"
+   * @example "pets"
+   * @example "authentication"
+   * @example "reports"
+   */
+  name: string
+  
+  /**
+   * A short description for the tag. GFM syntax can be used for rich text representation.
+   * 
+   * This description provides context about what operations belong to this tag
+   * and helps developers understand the purpose and scope of the tag.
+   * 
+   * @example "User management operations"
+   * @example "Pet store operations including CRUD operations for pets"
+   * @example "Authentication and authorization operations"
+   */
+  description?: string
+  
+  /**
+   * Additional external documentation for this tag.
+   * 
+   * This allows for more detailed documentation about the tag and its
+   * associated operations to be provided via external resources.
+   * 
+   * @example { description: "Find out more about user management", url: "https://example.com/docs/users" }
+   * @example { description: "Pet management API documentation", url: "https://petstore.example.com/docs" }
+   */
+  externalDocs?: ExternalDocumentation
+}

versions/2.0.0/xml.ts

@@ -0,0 +1,142 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * XML Object
+ * -----
+ *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms) 
+ * and the name property should be used to add that information.
+ *
+ * The XML Object provides additional metadata to describe the XML representation
+ * format of schema properties. It allows for precise control over how JSON
+ * schema definitions are translated to XML, including element naming, namespaces,
+ * attributes, and array wrapping.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 2.0     | {@link https://swagger.io/specification/v2/#xml-object | Swagger 2.0 XML Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Replaces the name of the element/attribute used for the described schema property.
+ * @key `namespace` - The URL of the namespace definition. Value SHOULD be in the form of a URL.
+ * @key `prefix` - The prefix to be used for the name.
+ * @key `attribute` - Declares whether the property definition translates to an attribute instead of an element. Default value is false.
+ * @key `wrapped` - MAY be used only for an array definition. Signifies whether the array is wrapped. Default value is false.
+ *
+ * @note
+ * All fields are optional. The `wrapped` property only takes effect when defined
+ * alongside `type` being `array` (outside the items). When `wrapped` is true,
+ * arrays are wrapped in a container element.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic XML element):
+ * ```ts
+ * const basicXml: XMLObject = {
+ *   name: "animal"
+ * };
+ * ```
+ *
+ * @example (XML attribute):
+ * ```ts
+ * const attributeXml: XMLObject = {
+ *   name: "id",
+ *   attribute: true
+ * };
+ * ```
+ *
+ * @example (namespaced XML):
+ * ```ts
+ * const namespacedXml: XMLObject = {
+ *   name: "name",
+ *   namespace: "http://swagger.io/schema/sample",
+ *   prefix: "sample"
+ * };
+ * ```
+ *
+ * @example (wrapped array):
+ * ```ts
+ * const wrappedArrayXml: XMLObject = {
+ *   name: "animals",
+ *   wrapped: true
+ * };
+ * ```
+ *
+ * @example (array items with custom name):
+ * ```ts
+ * const arrayItemsXml: XMLObject = {
+ *   name: "animal"
+ * };
+ * ```
+ *
+ * @example (complete XML definition):
+ * ```ts
+ * const completeXml: XMLObject = {
+ *   name: "person",
+ *   namespace: "http://example.com/schema",
+ *   prefix: "ex",
+ *   attribute: false,
+ *   wrapped: false
+ * };
+ * ```
+ */
+export interface XMLObject extends Extension {
+  /**
+   * Replaces the name of the element/attribute used for the described schema property. 
+   * When defined within the Items Object, it will affect the name of the individual 
+   * XML elements within the list. When defined alongside type being array (outside 
+   * the items), it will affect the wrapping element and only if wrapped is true.
+   * 
+   * @example "animal"
+   * @example "item"
+   * @example "person"
+   */
+  name?: string
+  
+  /**
+   * The URL of the namespace definition. Value SHOULD be in the form of a URL.
+   * 
+   * @example "http://example.com/schema/sample"
+   * @example "http://www.w3.org/2001/XMLSchema"
+   * @example "http://swagger.io/schema/sample"
+   */
+  namespace?: string
+  
+  /**
+   * The prefix to be used for the name.
+   * 
+   * @example "sample"
+   * @example "xs"
+   * @example "ex"
+   */
+  prefix?: string
+  
+  /**
+   * Declares whether the property definition translates to an attribute instead of an element. 
+   * Default value is false.
+   * 
+   * @default false
+   * @example true
+   * @example false
+   */
+  attribute?: boolean
+  
+  /**
+   * MAY be used only for an array definition. Signifies whether the array is wrapped 
+   * (for example, <books><book/><book/></books>) or unwrapped (<book/><book/>). 
+   * Default value is false. The definition takes effect only when defined alongside 
+   * type being array (outside the items).
+   * 
+   * @default false
+   * @example true
+   * @example false
+   */
+  wrapped?: boolean
+}

versions/3.0.x/components.ts

@@ -0,0 +1,123 @@
+import type { Schema } from "./schema"
+import type { Reference } from "./references"
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Components Object
+ * -----
+ *
+ * Holds a set of reusable objects for different aspects of the OAS. All objects defined
+ * within the components object will have no effect on the API unless they are explicitly
+ * referenced from properties outside the components object.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `schemas` - An object to hold reusable Schema Objects
+ * @key `responses` - An object to hold reusable Response Objects
+ * @key `parameters` - An object to hold reusable Parameter Objects
+ * @key `examples` - An object to hold reusable Example Objects
+ * @key `requestBodies` - An object to hold reusable Request Body Objects
+ * @key `headers` - An object to hold reusable Header Objects
+ * @key `securitySchemes` - An object to hold reusable Security Scheme Objects
+ * @key `links` - An object to hold reusable Link Objects
+ * @key `callbacks` - An object to hold reusable Callback Objects
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All objects defined within the components object will have no effect on the API unless
+ * they are explicitly referenced from properties outside the components object.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic components):
+ * ```ts
+ * const components: Components = {
+ *   schemas: {
+ *     User: {
+ *       type: "object",
+ *       properties: {
+ *         id: { type: "integer" },
+ *         name: { type: "string" }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface Components extends Extension {
+  /**
+   * An object to hold reusable Schema Objects.
+   * 
+   * @example { "User": { type: "object", properties: { id: { type: "integer" } } } }
+   */
+  schemas?: Record<string, Schema | Reference>
+
+  /**
+   * An object to hold reusable Response Objects.
+   * 
+   * @example { "NotFound": { description: "Resource not found" } }
+   */
+  responses?: Record<string, any>
+
+  /**
+   * An object to hold reusable Parameter Objects.
+   * 
+   * @example { "LimitParam": { name: "limit", in: "query", schema: { type: "integer" } } }
+   */
+  parameters?: Record<string, any>
+
+  /**
+   * An object to hold reusable Example Objects.
+   * 
+   * @example { "UserExample": { summary: "A user example", value: { id: 1, name: "John" } } }
+   */
+  examples?: Record<string, any>
+
+  /**
+   * An object to hold reusable Request Body Objects.
+   * 
+   * @example { "UserRequest": { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } }
+   */
+  requestBodies?: Record<string, any>
+
+  /**
+   * An object to hold reusable Header Objects.
+   * 
+   * @example { "RateLimit": { description: "Rate limit header", schema: { type: "integer" } } }
+   */
+  headers?: Record<string, any>
+
+  /**
+   * An object to hold reusable Security Scheme Objects.
+   * 
+   * @example { "ApiKeyAuth": { type: "apiKey", in: "header", name: "X-API-Key" } }
+   */
+  securitySchemes?: Record<string, any>
+
+  /**
+   * An object to hold reusable Link Objects.
+   * 
+   * @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } }
+   */
+  links?: Record<string, any>
+
+  /**
+   * An object to hold reusable Callback Objects.
+   * 
+   * @example { "MyCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { $ref: "#/components/requestBodies/SomeRequestBody" } } } } }
+   */
+  callbacks?: Record<string, any>
+}

versions/3.0.x/data-types/array.ts

@@ -0,0 +1,206 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Array Schema
+ * -----
+ *
+ * A schema for array data types with array-specific validation constraints.
+ * Only valid with `type: "array"` and includes array properties like
+ * `items`, `maxItems`, `minItems`, and `uniqueItems`.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "array"
+ * @key `items` - Schema for the items in the array
+ * @key `maxItems` - Maximum number of items in the array
+ * @key `minItems` - Minimum number of items in the array
+ * @key `uniqueItems` - Whether all items must be unique
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid array values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Array-specific constraints (`items`, `maxItems`, `minItems`, `uniqueItems`) are only
+ * valid with `type: "array"`. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic array):
+ * ```ts
+ * const arraySchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   description: "Array of strings"
+ * };
+ * ```
+ *
+ * @example (array with validation):
+ * ```ts
+ * const tagsSchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   minItems: 1,
+ *   maxItems: 10,
+ *   uniqueItems: true,
+ *   description: "Array of unique tags"
+ * };
+ * ```
+ *
+ * @example (array of objects):
+ * ```ts
+ * const usersSchema: ArraySchema = {
+ *   type: "array",
+ *   items: { $ref: "#/components/schemas/User" },
+ *   description: "Array of user objects"
+ * };
+ * ```
+ *
+ * @example (array with enum):
+ * ```ts
+ * const statusesSchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string", enum: ["active", "inactive"] },
+ *   description: "Array of status values"
+ * };
+ * ```
+ */
+export interface ArraySchema extends Extension {
+  /**
+   * The type of the schema. Must be "array" for array schemas.
+   * 
+   * @example "array"
+   */
+  type: "array"
+
+  /**
+   * A short title for the schema.
+   * 
+   * @example "Tags"
+   * @example "User List"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "Array of tag strings"
+   * @example "List of user objects"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example ["tag1", "tag2"]
+   * @example []
+   */
+  default?: any[]
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example ["example1", "example2"]
+   * @example [1, 2, 3]
+   */
+  example?: any[]
+
+  /**
+   * Enumeration of valid array values.
+   * 
+   * @example [["a", "b"], ["c", "d"]]
+   * @example [[1, 2], [3, 4]]
+   */
+  enum?: any[][]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "tags", wrapped: true }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this field", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+
+  // Array-specific validation constraints
+  /**
+   * Schema for the items in the array. This field is required for array schemas.
+   * 
+   * @example { type: "string" }
+   * @example { $ref: "#/components/schemas/User" }
+   */
+  items?: any // Will be properly typed as Schema | Reference when we set up the circular reference
+
+  /**
+   * Maximum number of items in the array. The value MUST be a non-negative integer.
+   * 
+   * @example 10
+   * @example 100
+   */
+  maxItems?: number
+
+  /**
+   * Minimum number of items in the array. The value MUST be a non-negative integer.
+   * 
+   * @example 1
+   * @example 0
+   */
+  minItems?: number
+
+  /**
+   * Whether all items in the array must be unique. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  uniqueItems?: boolean
+}

versions/3.0.x/data-types/boolean.ts

@@ -0,0 +1,165 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Boolean Schema
+ * -----
+ *
+ * A schema for boolean data types (true/false values) with basic validation.
+ * Only valid with `type: "boolean"` and includes common metadata properties
+ * but no boolean-specific validation constraints.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "boolean"
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid boolean values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Boolean schemas have no type-specific validation constraints beyond
+ * the basic metadata properties. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic boolean):
+ * ```ts
+ * const booleanSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   description: "A true/false value"
+ * };
+ * ```
+ *
+ * @example (boolean with default):
+ * ```ts
+ * const enabledSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   default: false,
+ *   description: "Whether the feature is enabled"
+ * };
+ * ```
+ *
+ * @example (boolean with enum):
+ * ```ts
+ * const statusSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   enum: [true, false],
+ *   default: false,
+ *   description: "Active status"
+ * };
+ * ```
+ *
+ * @example (read-only boolean):
+ * ```ts
+ * const computedSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   readOnly: true,
+ *   description: "Computed value that cannot be set directly"
+ * };
+ * ```
+ */
+export interface BooleanSchema extends Extension {
+  /**
+   * The type of the schema. Must be "boolean" for boolean schemas.
+   * 
+   * @example "boolean"
+   */
+  type: "boolean"
+
+  /**
+   * A short title for the schema.
+   * 
+   * @example "Is Active"
+   * @example "Enabled"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "Whether the user is active"
+   * @example "Feature enabled status"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example true
+   * @example false
+   */
+  default?: boolean
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example true
+   * @example false
+   */
+  example?: boolean
+
+  /**
+   * Enumeration of valid boolean values.
+   * 
+   * @example [true, false]
+   */
+  enum?: boolean[]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "isActive", attribute: true }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this field", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+}

versions/3.0.x/data-types/composition.ts

@@ -0,0 +1,207 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Composition Schema
+ * -----
+ *
+ * A schema that uses composition keywords (allOf, anyOf, oneOf, not) for schema
+ * composition and logical operations. These keywords are mutually exclusive with
+ * `$ref` but can appear with any validation keywords.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `allOf` - Array of schemas that must all be valid
+ * @key `anyOf` - Array of schemas where at least one must be valid
+ * @key `oneOf` - Array of schemas where exactly one must be valid
+ * @key `not` - Schema that must not be valid
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `discriminator` - Discriminator for polymorphism
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Composition keywords are mutually exclusive with `$ref` but can appear with
+ * any validation keywords. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (allOf composition):
+ * ```ts
+ * const composedSchema: CompositionSchema = {
+ *   allOf: [
+ *     { $ref: "#/components/schemas/BaseUser" },
+ *     { type: "object", required: ["id"] }
+ *   ],
+ *   description: "User with base properties plus required id"
+ * };
+ * ```
+ *
+ * @example (anyOf composition):
+ * ```ts
+ * const flexibleSchema: CompositionSchema = {
+ *   anyOf: [
+ *     { type: "string" },
+ *     { type: "integer" }
+ *   ],
+ *   description: "String or integer value"
+ * };
+ * ```
+ *
+ * @example (oneOf composition):
+ * ```ts
+ * const choiceSchema: CompositionSchema = {
+ *   oneOf: [
+ *     { $ref: "#/components/schemas/Dog" },
+ *     { $ref: "#/components/schemas/Cat" }
+ *   ],
+ *   discriminator: "petType",
+ *   description: "Either a dog or cat"
+ * };
+ * ```
+ *
+ * @example (not composition):
+ * ```ts
+ * const exclusionSchema: CompositionSchema = {
+ *   not: { type: "null" },
+ *   description: "Any value except null"
+ * };
+ * ```
+ */
+export interface CompositionSchema extends Extension {
+  /**
+   * A short title for the schema.
+   * 
+   * @example "Composed User"
+   * @example "Flexible Value"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "Schema composed from multiple base schemas"
+   * @example "Value that can be string or number"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example "default value"
+   * @example { name: "default" }
+   */
+  default?: any
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example "example value"
+   * @example { name: "example" }
+   */
+  example?: any
+
+  /**
+   * Enumeration of valid values.
+   * 
+   * @example ["value1", "value2"]
+   * @example [1, 2, 3]
+   */
+  enum?: any[]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "composed", wrapped: true }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this schema", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+
+  /**
+   * Discriminator for polymorphism. The property name used to differentiate between schemas.
+   * 
+   * @example "petType"
+   * @example "type"
+   */
+  discriminator?: any // Will be properly typed when we import Discriminator type
+
+  // Composition keywords (mutually exclusive)
+  /**
+   * Array of schemas that must all be valid for the instance to be valid.
+   * 
+   * @example [{ $ref: "#/components/schemas/Base" }, { type: "object", required: ["id"] }]
+   */
+  allOf?: any[] // Will be properly typed as (Schema | Reference)[] when we set up the circular reference
+
+  /**
+   * Array of schemas where at least one must be valid for the instance to be valid.
+   * 
+   * @example [{ type: "string" }, { type: "integer" }]
+   */
+  anyOf?: any[] // Will be properly typed as (Schema | Reference)[] when we set up the circular reference
+
+  /**
+   * Array of schemas where exactly one must be valid for the instance to be valid.
+   * 
+   * @example [{ $ref: "#/components/schemas/Dog" }, { $ref: "#/components/schemas/Cat" }]
+   */
+  oneOf?: any[] // Will be properly typed as (Schema | Reference)[] when we set up the circular reference
+
+  /**
+   * Schema that must not be valid for the instance to be valid.
+   * 
+   * @example { type: "null" }
+   * @example { type: "string", maxLength: 0 }
+   */
+  not?: any // Will be properly typed as Schema | Reference when we set up the circular reference
+}

versions/3.0.x/data-types/index.ts

@@ -0,0 +1,9 @@
+// Individual schema types
+export type { ReferenceSchema } from "./reference"
+export type { StringSchema } from "./string"
+export type { NumberSchema } from "./number"
+export type { IntegerSchema } from "./integer"
+export type { BooleanSchema } from "./boolean"
+export type { ArraySchema } from "./array"
+export type { ObjectSchema } from "./object"
+export type { CompositionSchema } from "./composition"

versions/3.0.x/data-types/integer.ts

@@ -0,0 +1,223 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Integer Schema
+ * -----
+ *
+ * A schema for integer data types (whole numbers) with integer-specific
+ * validation constraints. Only valid with `type: "integer"` and includes
+ * numeric properties like `multipleOf`, `maximum`, `minimum`, etc.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "integer"
+ * @key `format` - The extending format for the integer type
+ * @key `multipleOf` - Number must be a multiple of this value
+ * @key `maximum` - Maximum value (inclusive)
+ * @key `exclusiveMaximum` - Maximum value (exclusive)
+ * @key `minimum` - Minimum value (inclusive)
+ * @key `exclusiveMinimum` - Minimum value (exclusive)
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid integer values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Integer-specific constraints (`multipleOf`, `maximum`, `minimum`, etc.) are only
+ * valid with `type: "integer"`. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic integer):
+ * ```ts
+ * const integerSchema: IntegerSchema = {
+ *   type: "integer",
+ *   description: "A whole number"
+ * };
+ * ```
+ *
+ * @example (integer with format):
+ * ```ts
+ * const int32Schema: IntegerSchema = {
+ *   type: "integer",
+ *   format: "int32",
+ *   description: "32-bit signed integer"
+ * };
+ * ```
+ *
+ * @example (integer with validation):
+ * ```ts
+ * const ageSchema: IntegerSchema = {
+ *   type: "integer",
+ *   minimum: 0,
+ *   maximum: 150,
+ *   description: "Person's age in years"
+ * };
+ * ```
+ *
+ * @example (integer with enum):
+ * ```ts
+ * const statusCodeSchema: IntegerSchema = {
+ *   type: "integer",
+ *   enum: [200, 201, 400, 401, 404, 500],
+ *   description: "HTTP status code"
+ * };
+ * ```
+ */
+export interface IntegerSchema extends Extension {
+  /**
+   * The type of the schema. Must be "integer" for integer schemas.
+   * 
+   * @example "integer"
+   */
+  type: "integer"
+
+  /**
+   * The extending format for the integer type. See OpenAPI 3.0.x Data Type Formats for details.
+   * 
+   * @example "int32"
+   * @example "int64"
+   */
+  format?: string
+
+  /**
+   * A short title for the schema.
+   * 
+   * @example "User ID"
+   * @example "Age"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "The user's unique identifier"
+   * @example "Age in years"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example 0
+   * @example 1
+   */
+  default?: number
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example 42
+   * @example 100
+   */
+  example?: number
+
+  /**
+   * Enumeration of valid integer values.
+   * 
+   * @example [1, 2, 3, 4, 5]
+   * @example [0, 1, 2]
+   */
+  enum?: number[]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "userId", attribute: true }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this field", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+
+  // Integer-specific validation constraints
+  /**
+   * A number is valid against "multipleOf" if the result of the division
+   * of the instance by this keyword's value is an integer.
+   * 
+   * @example 1
+   * @example 2
+   * @example 5
+   */
+  multipleOf?: number
+
+  /**
+   * A number is valid against "maximum" if it is less than or equal to this value.
+   * 
+   * @example 100
+   * @example 2147483647
+   */
+  maximum?: number
+
+  /**
+   * A number is valid against "exclusiveMaximum" if it is strictly less than this value.
+   * 
+   * @example 100
+   * @example 1000
+   */
+  exclusiveMaximum?: number
+
+  /**
+   * A number is valid against "minimum" if it is greater than or equal to this value.
+   * 
+   * @example 0
+   * @example 1
+   */
+  minimum?: number
+
+  /**
+   * A number is valid against "exclusiveMinimum" if it is strictly greater than this value.
+   * 
+   * @example 0
+   * @example -1
+   */
+  exclusiveMinimum?: number
+}

versions/3.0.x/data-types/number.ts

@@ -0,0 +1,225 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Number Schema
+ * -----
+ *
+ * A schema for numeric data types (floating-point numbers) with numeric-specific
+ * validation constraints. Only valid with `type: "number"` and includes numeric
+ * properties like `multipleOf`, `maximum`, `minimum`, etc.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "number"
+ * @key `format` - The extending format for the number type
+ * @key `multipleOf` - Number must be a multiple of this value
+ * @key `maximum` - Maximum value (inclusive)
+ * @key `exclusiveMaximum` - Maximum value (exclusive)
+ * @key `minimum` - Minimum value (inclusive)
+ * @key `exclusiveMinimum` - Minimum value (exclusive)
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid number values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Numeric constraints (`multipleOf`, `maximum`, `minimum`, etc.) are only
+ * valid with `type: "number"` or `type: "integer"`. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic number):
+ * ```ts
+ * const numberSchema: NumberSchema = {
+ *   type: "number",
+ *   description: "A floating-point number"
+ * };
+ * ```
+ *
+ * @example (number with format):
+ * ```ts
+ * const floatSchema: NumberSchema = {
+ *   type: "number",
+ *   format: "float",
+ *   description: "Single precision floating-point number"
+ * };
+ * ```
+ *
+ * @example (number with validation):
+ * ```ts
+ * const priceSchema: NumberSchema = {
+ *   type: "number",
+ *   minimum: 0,
+ *   maximum: 999.99,
+ *   multipleOf: 0.01,
+ *   description: "Price in dollars with cent precision"
+ * };
+ * ```
+ *
+ * @example (number with enum):
+ * ```ts
+ * const ratingSchema: NumberSchema = {
+ *   type: "number",
+ *   enum: [1.0, 2.0, 3.0, 4.0, 5.0],
+ *   default: 3.0,
+ *   description: "Product rating from 1 to 5"
+ * };
+ * ```
+ */
+export interface NumberSchema extends Extension {
+  /**
+   * The type of the schema. Must be "number" for number schemas.
+   * 
+   * @example "number"
+   */
+  type: "number"
+
+  /**
+   * The extending format for the number type. See OpenAPI 3.0.x Data Type Formats for details.
+   * 
+   * @example "float"
+   * @example "double"
+   */
+  format?: string
+
+  /**
+   * A short title for the schema.
+   * 
+   * @example "Price"
+   * @example "Temperature"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "The price in dollars"
+   * @example "Temperature in Celsius"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example 0
+   * @example 25.5
+   */
+  default?: number
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example 19.99
+   * @example 98.6
+   */
+  example?: number
+
+  /**
+   * Enumeration of valid number values.
+   * 
+   * @example [1.0, 2.0, 3.0, 4.0, 5.0]
+   * @example [0.0, 0.5, 1.0]
+   */
+  enum?: number[]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "price", attribute: true }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this field", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+
+  // Number-specific validation constraints
+  /**
+   * A number is valid against "multipleOf" if the result of the division
+   * of the instance by this keyword's value is an integer.
+   * 
+   * @example 0.01
+   * @example 0.1
+   * @example 2
+   */
+  multipleOf?: number
+
+  /**
+   * A number is valid against "maximum" if it is less than or equal to this value.
+   * 
+   * @example 100
+   * @example 999.99
+   */
+  maximum?: number
+
+  /**
+   * A number is valid against "exclusiveMaximum" if it is strictly less than this value.
+   * 
+   * @example 100
+   * @example 1000
+   */
+  exclusiveMaximum?: number
+
+  /**
+   * A number is valid against "minimum" if it is greater than or equal to this value.
+   * 
+   * @example 0
+   * @example -273.15
+   */
+  minimum?: number
+
+  /**
+   * A number is valid against "exclusiveMinimum" if it is strictly greater than this value.
+   * 
+   * @example 0
+   * @example -100
+   */
+  exclusiveMinimum?: number
+}

versions/3.0.x/data-types/object.ts

@@ -0,0 +1,256 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Object Schema
+ * -----
+ *
+ * A schema for object data types with object-specific validation constraints.
+ * Only valid with `type: "object"` and includes object properties like
+ * `properties`, `required`, `additionalProperties`, etc.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "object"
+ * @key `properties` - Properties of the object
+ * @key `required` - Required property names
+ * @key `additionalProperties` - Additional properties schema
+ * @key `patternProperties` - Pattern-based properties
+ * @key `propertyNames` - Schema for property names
+ * @key `maxProperties` - Maximum number of properties
+ * @key `minProperties` - Minimum number of properties
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid object values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `discriminator` - Discriminator for polymorphism
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Object-specific constraints (`properties`, `required`, `additionalProperties`, etc.) are only
+ * valid with `type: "object"`. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic object):
+ * ```ts
+ * const objectSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "integer" }
+ *   },
+ *   description: "A person object"
+ * };
+ * ```
+ *
+ * @example (object with required properties):
+ * ```ts
+ * const userSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     id: { type: "integer" },
+ *     name: { type: "string" },
+ *     email: { type: "string", format: "email" }
+ *   },
+ *   required: ["id", "name", "email"],
+ *   description: "User object with required fields"
+ * };
+ * ```
+ *
+ * @example (object with additional properties):
+ * ```ts
+ * const flexibleSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     id: { type: "integer" }
+ *   },
+ *   additionalProperties: { type: "string" },
+ *   description: "Object allowing additional string properties"
+ * };
+ * ```
+ *
+ * @example (object with discriminator):
+ * ```ts
+ * const petSchema: ObjectSchema = {
+ *   type: "object",
+ *   discriminator: "petType",
+ *   properties: {
+ *     name: { type: "string" },
+ *     petType: { type: "string" }
+ *   },
+ *   required: ["name", "petType"],
+ *   description: "Base pet object with discriminator"
+ * };
+ * ```
+ */
+export interface ObjectSchema extends Extension {
+  /**
+   * The type of the schema. Must be "object" for object schemas.
+   * 
+   * @example "object"
+   */
+  type: "object"
+
+  /**
+   * A short title for the schema.
+   * 
+   * @example "User"
+   * @example "Product"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "A user object containing basic information"
+   * @example "Product information with pricing"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example { name: "John", age: 30 }
+   * @example {}
+   */
+  default?: Record<string, any>
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example { name: "Jane", age: 25 }
+   * @example { id: 1, title: "Sample" }
+   */
+  example?: Record<string, any>
+
+  /**
+   * Enumeration of valid object values.
+   * 
+   * @example [{ name: "John" }, { name: "Jane" }]
+   * @example [{ status: "active" }, { status: "inactive" }]
+   */
+  enum?: Record<string, any>[]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "user", wrapped: false }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this object", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+
+  /**
+   * Discriminator for polymorphism. The property name used to differentiate between schemas.
+   * 
+   * @example "petType"
+   * @example "type"
+   */
+  discriminator?: any // Will be properly typed when we import Discriminator type
+
+  // Object-specific validation constraints
+  /**
+   * Properties of the object. Each property name maps to a schema definition.
+   * 
+   * @example { name: { type: "string" }, age: { type: "integer" } }
+   * @example { id: { $ref: "#/components/schemas/Id" } }
+   */
+  properties?: Record<string, any> // Will be properly typed as Schema | Reference when we set up the circular reference
+
+  /**
+   * Array of property names that are required. Properties not listed here are optional.
+   * 
+   * @example ["id", "name"]
+   * @example ["email"]
+   */
+  required?: string[]
+
+  /**
+   * Schema for additional properties not defined in the properties object.
+   * Can be a boolean or a schema.
+   * 
+   * @example true
+   * @example false
+   * @example { type: "string" }
+   */
+  additionalProperties?: boolean | any // Will be properly typed as Schema | Reference when we set up the circular reference
+
+  /**
+   * Pattern-based properties using regular expressions as keys.
+   * 
+   * @example { "^S_": { type: "string" } }
+   * @example { "^[0-9]+$": { type: "integer" } }
+   */
+  patternProperties?: Record<string, any> // Will be properly typed as Schema | Reference when we set up the circular reference
+
+  /**
+   * Schema for property names. If present, property names must conform to this schema.
+   * 
+   * @example { type: "string", pattern: "^[a-zA-Z][a-zA-Z0-9]*$" }
+   */
+  propertyNames?: any // Will be properly typed as Schema | Reference when we set up the circular reference
+
+  /**
+   * Maximum number of properties in the object. The value MUST be a non-negative integer.
+   * 
+   * @example 10
+   * @example 50
+   */
+  maxProperties?: number
+
+  /**
+   * Minimum number of properties in the object. The value MUST be a non-negative integer.
+   * 
+   * @example 1
+   * @example 2
+   */
+  minProperties?: number
+}

versions/3.0.x/data-types/reference.ts

@@ -0,0 +1,80 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Reference Schema
+ * -----
+ *
+ * A schema that contains only a reference to another schema definition.
+ * When a schema contains `$ref`, no other sibling keys are allowed except
+ * `description` and extensions (`x-...`).
+ *
+ * This enforces the OpenAPI 3.0.x rule that `$ref` is mutually exclusive
+ * with all other schema properties except description and extensions.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `$ref` - The reference string. MUST be a valid JSON Reference.
+ * @key `description` - A short description of the referenced schema.
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * When using `$ref`, no other schema properties are allowed except
+ * `description` and extensions. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple reference):
+ * ```ts
+ * const refSchema: ReferenceSchema = {
+ *   $ref: "#/components/schemas/User"
+ * };
+ * ```
+ *
+ * @example (reference with description):
+ * ```ts
+ * const refSchema: ReferenceSchema = {
+ *   $ref: "#/components/schemas/Pet",
+ *   description: "A reference to the Pet schema"
+ * };
+ * ```
+ *
+ * @example (reference with extensions):
+ * ```ts
+ * const refSchema: ReferenceSchema = {
+ *   $ref: "#/components/schemas/Order",
+ *   description: "Order information",
+ *   "x-custom-property": "value"
+ * };
+ * ```
+ */
+export interface ReferenceSchema extends Extension {
+  /**
+   * The reference string. MUST be a valid JSON Reference.
+   * 
+   * @example "#/components/schemas/User"
+   * @example "#/components/responses/NotFound"
+   * @example "#/components/parameters/LimitParam"
+   */
+  $ref: string
+
+  /**
+   * A short description of the referenced schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "A reference to the User schema"
+   * @example "Pet object definition"
+   */
+  description?: string
+}

versions/3.0.x/data-types/string.ts

@@ -0,0 +1,207 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * String Schema
+ * -----
+ *
+ * A schema for string data types with string-specific validation constraints.
+ * Only valid with `type: "string"` and includes string-specific properties
+ * like `maxLength`, `minLength`, and `pattern`.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Must be "string"
+ * @key `format` - The extending format for the string type
+ * @key `maxLength` - Maximum length of the string
+ * @key `minLength` - Minimum length of the string
+ * @key `pattern` - Regular expression pattern the string must match
+ * @key `title` - A short title for the schema
+ * @key `description` - A short description of the schema
+ * @key `default` - Default value for the schema
+ * @key `example` - Example value for the schema
+ * @key `enum` - Enumeration of valid string values
+ * @key `readOnly` - Whether the property is read-only
+ * @key `writeOnly` - Whether the property is write-only
+ * @key `xml` - XML representation metadata
+ * @key `externalDocs` - Additional external documentation
+ * @key `deprecated` - Whether the schema is deprecated
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * String-specific constraints (`maxLength`, `minLength`, `pattern`) are only
+ * valid with `type: "string"`. This is enforced by the type system.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic string):
+ * ```ts
+ * const stringSchema: StringSchema = {
+ *   type: "string",
+ *   description: "A simple string field"
+ * };
+ * ```
+ *
+ * @example (string with format):
+ * ```ts
+ * const emailSchema: StringSchema = {
+ *   type: "string",
+ *   format: "email",
+ *   description: "Email address"
+ * };
+ * ```
+ *
+ * @example (string with validation):
+ * ```ts
+ * const passwordSchema: StringSchema = {
+ *   type: "string",
+ *   minLength: 8,
+ *   maxLength: 128,
+ *   pattern: "^[a-zA-Z0-9!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>\\/?]+$",
+ *   description: "Password with length and character requirements"
+ * };
+ * ```
+ *
+ * @example (string with enum):
+ * ```ts
+ * const statusSchema: StringSchema = {
+ *   type: "string",
+ *   enum: ["active", "inactive", "pending"],
+ *   default: "pending",
+ *   description: "User status"
+ * };
+ * ```
+ */
+export interface StringSchema extends Extension {
+  /**
+   * The type of the schema. Must be "string" for string schemas.
+   * 
+   * @example "string"
+   */
+  type: "string"
+
+  /**
+   * The extending format for the string type. See OpenAPI 3.0.x Data Type Formats for details.
+   * 
+   * @example "email"
+   * @example "date"
+   * @example "uuid"
+   * @example "uri"
+   */
+  format?: string
+
+  /**
+   * A short title for the schema.
+   * 
+   * @example "User Name"
+   * @example "Email Address"
+   */
+  title?: string
+
+  /**
+   * A short description of the schema. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "The user's full name"
+   * @example "Email address in RFC 5322 format"
+   */
+  description?: string
+
+  /**
+   * The default value for the schema.
+   * 
+   * @example "John Doe"
+   * @example "user@example.com"
+   */
+  default?: string
+
+  /**
+   * Example value for the schema.
+   * 
+   * @example "Jane Smith"
+   * @example "admin@example.com"
+   */
+  example?: string
+
+  /**
+   * Enumeration of valid string values.
+   * 
+   * @example ["active", "inactive", "pending"]
+   * @example ["red", "green", "blue"]
+   */
+  enum?: string[]
+
+  /**
+   * Whether the property is read-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  readOnly?: boolean
+
+  /**
+   * Whether the property is write-only. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  writeOnly?: boolean
+
+  /**
+   * XML representation metadata for the schema.
+   * 
+   * @example { name: "userName", attribute: false }
+   */
+  xml?: any // Will be properly typed when we import XML type
+
+  /**
+   * Additional external documentation for the schema.
+   * 
+   * @example { description: "Find out more about this field", url: "https://example.com/docs" }
+   */
+  externalDocs?: any // Will be properly typed when we import ExternalDocumentation type
+
+  /**
+   * Whether the schema is deprecated. Default value is false.
+   * 
+   * @default false
+   * @example true
+   */
+  deprecated?: boolean
+
+  // String-specific validation constraints
+  /**
+   * Maximum length of the string. The value MUST be a non-negative integer.
+   * 
+   * @example 100
+   * @example 255
+   */
+  maxLength?: number
+
+  /**
+   * Minimum length of the string. The value MUST be a non-negative integer.
+   * 
+   * @example 1
+   * @example 8
+   */
+  minLength?: number
+
+  /**
+   * Regular expression pattern the string must match. The pattern MUST be a valid regular expression.
+   * 
+   * @example "^[a-zA-Z0-9]+$"
+   * @example "^\\d{4}-\\d{2}-\\d{2}$"
+   */
+  pattern?: string
+}

versions/3.0.x/extensions.ts

@@ -0,0 +1,47 @@
+/**
+ * -----
+ * Extension Type
+ * -----
+ *
+ * Vendor extensions allow adding custom properties to OpenAPI objects.
+ * All extension property names MUST begin with "x-" followed by any valid identifier.
+ * The value can be any valid JSON value (null, primitive, array, or object).
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#specification-extensions | OpenAPI 3.0.4 Extensions} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#specification-extensions | OpenAPI 3.0.3 Extensions} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#specification-extensions | OpenAPI 3.0.2 Extensions} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#specification-extensions | OpenAPI 3.0.1 Extensions} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#specification-extensions | OpenAPI 3.0.0 Extensions} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All extension property names MUST begin with "x-".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple extension):
+ * ```ts
+ * const extension: Extension = {
+ *   "x-internal-id": "12345"
+ * };
+ * ```
+ *
+ * @example (complex extension):
+ * ```ts
+ * const extension: Extension = {
+ *   "x-custom-feature": { enabled: true, version: "1.0" }
+ * };
+ * ```
+ */
+export type Extension = {
+  [K in `x-${string}`]: unknown
+}

versions/3.0.x/externalDocs.ts

@@ -0,0 +1,57 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * External Documentation Object
+ * -----
+ *
+ * Allows referencing an external resource for extended documentation.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `description` - Optional A short description of the target documentation
+ * @key `url` - Required The URL for the target documentation
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `url` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple external docs):
+ * ```ts
+ * const externalDocs: ExternalDocumentation = {
+ *   description: "Find more info here",
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ */
+export interface ExternalDocumentation extends Extension {
+  /** 
+   * A short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "Find more info here"
+   * @example "Additional documentation for this API"
+   */
+  description?: string
+  
+  /** 
+   * The URL for the target documentation. MUST be in the format of a URL.
+   * 
+   * @example "https://example.com/docs"
+   * @example "https://api.example.com/documentation"
+   */
+  url: string
+}

versions/3.0.x/index.ts

@@ -0,0 +1,65 @@
+// Centralized exports for OpenAPI 3.0 types
+// This file serves as the main entry point for all OpenAPI 3.0 type definitions
+
+// Export the main specification type
+export type { Specification } from "./spec"
+
+// Re-export all types for convenience
+export type {
+  // Core types
+  Extension
+} from "./extensions"
+
+export type {
+  Contact,
+  // Info types
+  Info, License
+} from "./info"
+
+export type {
+  // Server types
+  Server,
+  ServerVariable
+} from "./servers"
+
+export type {
+  Callback, Encoding, Example, Header, Link, MediaType, Operation,
+  Parameter,
+  // Path types
+  PathItemObject, RequestBody, Response
+} from "./paths"
+
+export type {
+  // Components types
+  Components
+} from "./components"
+
+export type {
+  Discriminator,
+  // Schema types
+  Schema
+} from "./schema"
+
+export type {
+  // XML types
+  XML
+} from "./xml"
+
+export type {
+  OAuthFlow, OAuthFlows, SecurityRequirement,
+  // Security types
+  SecurityScheme
+} from "./security"
+
+export type {
+  // Utility types
+  Tag
+} from "./tags"
+
+export type {
+  ExternalDocumentation,
+} from "./external-documentation"
+
+export type {
+  Reference,
+} from "./references"

versions/3.0.x/info.ts

@@ -0,0 +1,295 @@
+import type { Extension } from "./extensions"
+import type { LicenseName, LicenseURL } from "../License"
+import type { ExternalDocumentation } from "./externalDocs"
+
+/**
+ * -----
+ * Info Object
+ * -----
+ *
+ * The object provides metadata about the API.
+ * The metadata MAY be used by the clients if needed, and MAY be presented in
+ * editing or documentation generation tools for convenience.
+ *
+ * The Info Object provides metadata about the API. This metadata can be used by
+ * clients if needed, and can be presented in the OpenAPI-UI for convenience.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `title` - Required The title of the application
+ * @key `description` - Optional A short description of the application
+ * @key `termsOfService` - Optional A URL to the Terms of Service for the API
+ * @key `contact` - Optional The contact information for the exposed API
+ * @key `license` - Optional The license information for the exposed API
+ * @key `version` - Required The version of the OpenAPI document
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `title` and `version` fields are required. In OpenAPI 3.0.1+, the `description`
+ * field was clarified to support CommonMark syntax for rich text representation.
+ * The `termsOfService` field must be a valid URL format.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (minimal info):
+ * ```ts
+ * const info: Info = {
+ *   title: "Sample Pet Store App",
+ *   version: "1.0.1"
+ * };
+ * ```
+ *
+ * @example (full info object):
+ * ```ts
+ * const info: Info = {
+ *   title: "Sample Pet Store App",
+ *   description: "This is a sample server for a pet store.",
+ *   termsOfService: "http://example.com/terms/",
+ *   contact: {
+ *     name: "API Support",
+ *     url: "http://www.example.com/support",
+ *     email: "support@example.com"
+ *   },
+ *   license: {
+ *     name: "Apache 2.0",
+ *     url: "http://www.apache.org/licenses/LICENSE-2.0.html"
+ *   },
+ *   version: "1.0.1"
+ * };
+ * ```
+ */
+export interface Info extends Extension {
+  /** 
+   * The title of the application. This field is required.
+   * 
+   * @example "Sample Pet Store App"
+   * @example "My API"
+   */
+  title: string
+  
+  /** 
+   * A short description of the application. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "This is a sample server for a pet store."
+   * @example "A comprehensive API for managing user data"
+   */
+  description?: string
+  
+  /** 
+   * A URL to the Terms of Service for the API. MUST be in the format of a URL.
+   * 
+   * @example "http://example.com/terms/"
+   * @example "https://example.com/terms"
+   */
+  termsOfService?: string
+  
+  /** 
+   * The contact information for the exposed API.
+   * 
+   * @example { name: "API Support", email: "support@example.com" }
+   */
+  contact?: Contact
+  
+  /** 
+   * The license information for the exposed API.
+   * 
+   * @example { name: "Apache 2.0", url: "http://www.apache.org/licenses/LICENSE-2.0.html" }
+   */
+  license?: License
+  
+  /** 
+   * The version of the OpenAPI document (which is distinct from the OpenAPI Specification version 
+   * or the API implementation version). This field is required.
+   * 
+   * @example "1.0.1"
+   * @example "2.0.0"
+   */
+  version: string
+}
+
+/**
+ * -----
+ * Contact Object
+ * -----
+ *
+ * Contact information for the exposed API.
+ *
+ * The Contact Object provides contact information for the exposed API. It can
+ * include the name, URL, and email address of the contact person or organization.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Optional The identifying name of the contact person/organization
+ * @key `url` - Optional A URL pointing to the contact information
+ * @key `email` - Optional The email address of the contact person/organization
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All fields are optional. In OpenAPI 3.0.1+, the `url` field was clarified to
+ * must be in the format of a URL, and the `email` field must be in the format
+ * of an email address.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (full contact object):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "API Support",
+ *   url: "http://www.example.com/support",
+ *   email: "support@example.com"
+ * };
+ * ```
+ *
+ * @example (just name + email):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "Jane Doe",
+ *   email: "jane.doe@example.com"
+ * };
+ * ```
+ *
+ * @example (with extension):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "Internal API Team",
+ *   email: "api-team@example.com",
+ *   "x-slack": "#api-support"
+ * };
+ * ```
+ */
+export interface Contact extends Extension {
+  /** 
+   * The identifying name of the contact person/organization.
+   * 
+   * @example "API Support"
+   * @example "John Doe"
+   */
+  name?: string
+  
+  /** 
+   * The URL pointing to the contact information. MUST be in the format of a URL.
+   * 
+   * @example "http://www.example.com/support"
+   * @example "https://example.com/contact"
+   */
+  url?: string
+  
+  /** 
+   * The email address of the contact person/organization. MUST be in the format of an email address.
+   * 
+   * @example "support@example.com"
+   * @example "contact@example.com"
+   */
+  email?: string
+}
+
+/**
+ * -----
+ * License Object
+ * -----
+ *
+ * License information for the exposed API.
+ *
+ * The License Object provides license information for the exposed API. It can
+ * include the name of the license and optionally a URL to the license text.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Required The license name used for the API
+ * @key `url` - Optional A URL to the license used for the API
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `name` field is required. The `url` field is optional but recommended.
+ * In OpenAPI 3.0.1+, the `url` field was clarified to must be in the format
+ * of a URL when provided.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (MIT License):
+ * ```ts
+ * const license: License = {
+ *   name: "MIT License",
+ *   url: "https://opensource.org/license/mit/"
+ * };
+ * ```
+ *
+ * @example (Apache 2.0):
+ * ```ts
+ * const license: License = {
+ *   name: "Apache 2.0",
+ *   url: "http://www.apache.org/licenses/LICENSE-2.0.html"
+ * };
+ * ```
+ *
+ * @example (license without URL):
+ * ```ts
+ * const license: License = {
+ *   name: "Proprietary License"
+ * };
+ * ```
+ *
+ * @example (with extension):
+ * ```ts
+ * const license: License = {
+ *   name: "Custom License",
+ *   url: "https://example.com/license",
+ *   "x-license-version": "1.0"
+ * };
+ * ```
+ */
+export interface License extends Extension {
+  /** 
+   * The license name used for the API. This field is required.
+   * 
+   * @example "MIT License"
+   * @example "Apache 2.0"
+   * @example "Proprietary License"
+   */
+  name: LicenseName
+  
+  /** 
+   * A URL to the license used for the API. MUST be in the format of a URL.
+   * 
+   * @example "https://opensource.org/license/mit/"
+   * @example "http://www.apache.org/licenses/LICENSE-2.0.html"
+   * @example "https://example.com/licenses/proprietary-1.0"
+   */
+  url?: LicenseURL
+}

versions/3.0.x/references.ts

@@ -0,0 +1,49 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Reference Object
+ * -----
+ *
+ * A simple object to allow referencing other components in the specification, 
+ * internally and externally.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#reference-object | OpenAPI 3.0.4 Reference} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#reference-object | OpenAPI 3.0.3 Reference} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#reference-object | OpenAPI 3.0.2 Reference} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#reference-object | OpenAPI 3.0.1 Reference} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#reference-object | OpenAPI 3.0.0 Reference} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `$ref` - Required The reference string
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `$ref` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple reference):
+ * ```ts
+ * const reference: Reference = {
+ *   $ref: "#/components/schemas/User"
+ * };
+ * ```
+ */
+export interface Reference extends Extension {
+  /** 
+   * The reference string. MUST be a valid JSON Reference.
+   * 
+   * @example "#/components/schemas/User"
+   * @example "#/components/responses/NotFound"
+   * @example "#/components/parameters/LimitParam"
+   */
+  $ref: string
+}

versions/3.0.x/schema.ts

@@ -0,0 +1,246 @@
+import type {
+  ReferenceSchema,
+  StringSchema,
+  NumberSchema,
+  IntegerSchema,
+  BooleanSchema,
+  ArraySchema,
+  ObjectSchema,
+  CompositionSchema,
+} from "./data-types"
+import type { Reference } from "./references"
+import type { XML } from "./xml"
+import type { ExternalDocumentation } from "./externalDocs"
+import type { Components } from "./components"
+// Discriminator will be defined below to avoid circular reference
+
+/**
+ * -----
+ * Schema Object (OpenAPI 3.0.x)
+ * -----
+ *
+ * The Schema Object allows the definition of input and output data types.
+ * These types can be objects, but also primitives and arrays. This object
+ * is based on JSON Schema Specification Draft 7 and uses the same
+ * formatting rules.
+ *
+ * This discriminated union enforces the OpenAPI 3.0.x mutual-exclusion and
+ * co-occurrence rules, ensuring that only valid combinations of properties
+ * can be used together.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} |
+ *
+ * -----
+ * Schema Types
+ * -----
+ *
+ * @key `ReferenceSchema` - Reference-only schemas ($ref with optional description)
+ * @key `StringSchema` - String schemas with string-specific constraints
+ * @key `NumberSchema` - Number schemas with numeric constraints
+ * @key `IntegerSchema` - Integer schemas with integer constraints
+ * @key `BooleanSchema` - Boolean schemas with basic validation
+ * @key `ArraySchema` - Array schemas with array-specific constraints
+ * @key `ObjectSchema` - Object schemas with object-specific constraints
+ * @key `CompositionSchema` - Composition schemas (allOf/anyOf/oneOf/not)
+ *
+ * @note
+ * The discriminated union enforces these OpenAPI 3.0.x rules:
+ * - `$ref` is mutually exclusive with all other properties except description and extensions
+ * - Type-specific constraints are only valid with their corresponding type
+ * - Composition keywords are mutually exclusive with `$ref` but can appear with validation keywords
+ * - Metadata keywords can appear with any valid combination
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (reference schema):
+ * ```ts
+ * const refSchema: Schema = {
+ *   $ref: "#/components/schemas/User",
+ *   description: "A reference to the User schema"
+ * };
+ * ```
+ *
+ * @example (string schema):
+ * ```ts
+ * const stringSchema: Schema = {
+ *   type: "string",
+ *   minLength: 1,
+ *   maxLength: 100,
+ *   pattern: "^[a-zA-Z]+$"
+ * };
+ * ```
+ *
+ * @example (object schema):
+ * ```ts
+ * const objectSchema: Schema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "integer" }
+ *   },
+ *   required: ["name"]
+ * };
+ * ```
+ *
+ * @example (composition schema):
+ * ```ts
+ * const composedSchema: Schema = {
+ *   allOf: [
+ *     { $ref: "#/components/schemas/BaseUser" },
+ *     { type: "object", required: ["id"] }
+ *   ]
+ * };
+ * ```
+ */
+export type Schema = 
+  | ReferenceSchema
+  | StringSchema
+  | NumberSchema
+  | IntegerSchema
+  | BooleanSchema
+  | ArraySchema
+  | ObjectSchema
+  | CompositionSchema
+
+/**
+ * -----
+ * Discriminator Object
+ * -----
+ *
+ * When request bodies or response payloads may be one of a number of different schemas,
+ * a discriminator object can be used to aid in serialization, deserialization, and validation.
+ * The discriminator is a specific object in a schema which is used to inform the consumer
+ * of the specification of an alternative schema based on the value associated with it.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#discriminator-object | OpenAPI 3.0.0 Discriminator Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#discriminator-object | OpenAPI 3.0.1 Discriminator Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#discriminator-object | OpenAPI 3.0.2 Discriminator Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#discriminator-object | OpenAPI 3.0.3 Discriminator Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#discriminator-object | OpenAPI 3.0.4 Discriminator Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `propertyName` - The name of the property in the schema that is used as a discriminator
+ * @key `mapping` - An object to hold mappings between payload values and schema names or references
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The discriminator property name MUST be defined at this schema and it MUST be in the
+ * required property list. When used, the value MUST be the name of this schema or any
+ * schema that inherits it.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic discriminator):
+ * ```ts
+ * const discriminator: Discriminator = {
+ *   propertyName: "petType"
+ * };
+ * ```
+ *
+ * @example (discriminator with mapping):
+ * ```ts
+ * const discriminator: Discriminator = {
+ *   propertyName: "petType",
+ *   mapping: {
+ *     "dog": "#/components/schemas/Dog",
+ *     "cat": "#/components/schemas/Cat"
+ *   }
+ * };
+ * ```
+ */
+export interface Discriminator {
+  /**
+   * The name of the property in the schema that is used as a discriminator.
+   * 
+   * @example "petType"
+   * @example "type"
+   * @example "kind"
+   */
+  propertyName: string
+
+  /**
+   * An object to hold mappings between payload values and schema names or references.
+   * 
+   * @example { "dog": "Dog", "cat": "Cat" }
+   * @example { "admin": "AdminUser", "user": "RegularUser" }
+   */
+  mapping?: Record<string, string>
+}
+
+/**
+ * -----
+ * XML Object
+ * -----
+ *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms) 
+ * and the name property should be used to add that information.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object} |
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Replaces the name of the element/attribute used for the described schema property
+ * @key `namespace` - The URL of the namespace definition
+ * @key `prefix` - The prefix to be used for the name
+ * @key `attribute` - Declares whether the property definition translates to an attribute instead of an element
+ * @key `wrapped` - Signifies whether the array is wrapped
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * When defined within items, it will affect the name of the individual XML elements within the list.
+ * When defined alongside type being array (outside the items), it will affect the wrapping element
+ * and only if wrapped is true.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic XML):
+ * ```ts
+ * const xml: XML = {
+ *   name: "animal",
+ *   namespace: "http://example.com/schema",
+ *   prefix: "ex"
+ * };
+ * ```
+ *
+ * @example (XML attribute):
+ * ```ts
+ * const xml: XML = {
+ *   name: "id",
+ *   attribute: true
+ * };
+ * ```
+ *
+ * @example (wrapped array):
+ * ```ts
+ * const xml: XML = {
+ *   name: "items",
+ *   wrapped: true
+ * };
+ * ```
+ */

versions/3.0.x/security.ts

@@ -0,0 +1,225 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Security Scheme Object
+ * -----
+ *
+ * Defines a security scheme that can be used by the operations.
+ * Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter),
+ * OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749,
+ * and OpenID Connect Discovery.
+ *
+ * The Security Scheme Object defines a security scheme that can be used by the operations.
+ * It supports various authentication methods including HTTP authentication, API keys,
+ * OAuth2 flows, and OpenID Connect Discovery.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Required The type of the security scheme
+ * @key `description` - Optional A short description for security scheme
+ * @key `name` - Optional The name of the header, query or cookie parameter to be used
+ * @key `in` - Optional The location of the API key
+ * @key `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header
+ * @key `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted
+ * @key `flows` - Optional An object containing configuration information for the flow types supported
+ * @key `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `type` field is required. The `name` and `in` fields are required for apiKey type.
+ * In OpenAPI 3.0.1+, the `bearerFormat` field was clarified to be a hint to the client
+ * about how the bearer token is formatted, and the `openIdConnectUrl` field was clarified
+ * to be a URL that can be used to discover OAuth2 configuration values.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (API key):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "apiKey",
+ *   in: "header",
+ *   name: "X-API-Key"
+ * };
+ * ```
+ *
+ * @example (OAuth2):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "oauth2",
+ *   flows: {
+ *     authorizationCode: {
+ *       authorizationUrl: "https://example.com/oauth/authorize",
+ *       tokenUrl: "https://example.com/oauth/token",
+ *       scopes: {
+ *         "read": "Read access",
+ *         "write": "Write access"
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example (HTTP Bearer):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "http",
+ *   scheme: "bearer",
+ *   bearerFormat: "JWT"
+ * };
+ * ```
+ *
+ * @example (OpenID Connect):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "openIdConnect",
+ *   openIdConnectUrl: "https://example.com/.well-known/openid_configuration"
+ * };
+ * ```
+ */
+export interface SecurityScheme extends Extension {
+  /** 
+   * The type of the security scheme. This field is required.
+   * 
+   * @example "apiKey"
+   * @example "http"
+   * @example "oauth2"
+   * @example "openIdConnect"
+   */
+  type: "apiKey" | "http" | "oauth2" | "openIdConnect"
+  
+  /** 
+   * A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "API key authentication"
+   * @example "OAuth 2.0 authentication"
+   */
+  description?: string
+  
+  /** 
+   * The name of the header, query or cookie parameter to be used.
+   * 
+   * @example "X-API-Key"
+   * @example "Authorization"
+   */
+  name?: string
+  
+  /** 
+   * The location of the API key. Valid values are "query", "header" or "cookie".
+   * 
+   * @example "query"
+   * @example "header"
+   * @example "cookie"
+   */
+  in?: "query" | "header" | "cookie"
+  
+  /** 
+   * The name of the HTTP Authorization scheme to be used in the Authorization header.
+   * 
+   * @example "bearer"
+   * @example "basic"
+   */
+  scheme?: string
+  
+  /** 
+   * A hint to the client to identify how the bearer token is formatted.
+   * 
+   * @example "JWT"
+   * @example "Bearer"
+   */
+  bearerFormat?: string
+  
+  /** 
+   * An object containing configuration information for the flow types supported.
+   * 
+   * @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } }
+   */
+  flows?: OAuthFlows
+  
+  /** 
+   * OpenId Connect URL to discover OAuth2 configuration values.
+   * 
+   * @example "https://example.com/.well-known/openid_configuration"
+   */
+  openIdConnectUrl?: string
+}
+
+export interface OAuthFlows extends Extension {
+  /** 
+   * Configuration for the OAuth Implicit flow.
+   * 
+   * @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { read: "Read access" } }
+   */
+  implicit?: OAuthFlow
+  
+  /** 
+   * Configuration for the OAuth Resource Owner Password flow.
+   * 
+   * @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } }
+   */
+  password?: OAuthFlow
+  
+  /** 
+   * Configuration for the OAuth Client Credentials flow.
+   * 
+   * @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } }
+   */
+  clientCredentials?: OAuthFlow
+  
+  /** 
+   * Configuration for the OAuth Authorization Code flow.
+   * 
+   * @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } }
+   */
+  authorizationCode?: OAuthFlow
+}
+
+export interface OAuthFlow extends Extension {
+  /** 
+   * The authorization URL to be used for this flow. This MUST be in the form of a URL.
+   * 
+   * @example "https://example.com/oauth/authorize"
+   * @example "https://api.example.com/oauth/authorize"
+   */
+  authorizationUrl?: string
+  
+  /** 
+   * The token URL to be used for this flow. This MUST be in the form of a URL.
+   * 
+   * @example "https://example.com/oauth/token"
+   * @example "https://api.example.com/oauth/token"
+   */
+  tokenUrl?: string
+  
+  /** 
+   * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+   * 
+   * @example "https://example.com/oauth/refresh"
+   * @example "https://api.example.com/oauth/refresh"
+   */
+  refreshUrl?: string
+  
+  /** 
+   * The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+   * 
+   * @example { "read": "Read access", "write": "Write access" }
+   * @example { "admin": "Administrative access" }
+   */
+  scopes?: Record<string, string>
+}
+
+export interface SecurityRequirement {
+  [schemeName: string]: string[]
+}

versions/3.0.x/servers.ts

@@ -0,0 +1,197 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Server Object
+ * -----
+ *
+ * An object representing a Server.
+ *
+ * The Server Object represents a server that hosts the API. It can contain a URL,
+ * description, and server variables for URL template substitution.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#server-object | OpenAPI 3.0.4 Server} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#server-object | OpenAPI 3.0.3 Server} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#server-object | OpenAPI 3.0.2 Server} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#server-object | OpenAPI 3.0.1 Server} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#server-object | OpenAPI 3.0.0 Server} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `url` - Required A URL to the target host
+ * @key `description` - Optional An optional string describing the host designated by the URL
+ * @key `variables` - Optional A map between a variable name and its value
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `url` field is required. The `url` supports Server Variables and MAY be relative.
+ * In OpenAPI 3.0.1+, the `url` field was clarified to support Server Variables and
+ * MAY be relative to indicate that the host location is relative to the location
+ * where the OpenAPI document is being served.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple server):
+ * ```ts
+ * const server: Server = {
+ *   url: "https://development.gigantic-server.com/v1",
+ *   description: "Development server"
+ * };
+ * ```
+ *
+ * @example (server with variables):
+ * ```ts
+ * const server: Server = {
+ *   url: "https://{username}.gigantic-server.com:{port}/{basePath}",
+ *   description: "The production API server",
+ *   variables: {
+ *     username: {
+ *       default: "demo",
+ *       description: "this value is assigned by the service provider"
+ *     },
+ *     port: {
+ *       enum: ["8443", "443"],
+ *       default: "8443"
+ *     },
+ *     basePath: {
+ *       default: "v2"
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example (relative server):
+ * ```ts
+ * const server: Server = {
+ *   url: "/v1",
+ *   description: "Relative server URL"
+ * };
+ * ```
+ */
+export interface Server extends Extension {
+  /** 
+   * A URL to the target host. This URL supports Server Variables and MAY be relative, 
+   * to indicate that the host location is relative to the location where the OpenAPI 
+   * document is being served. Variable substitutions will be made when a variable 
+   * is named in {brackets}.
+   * 
+   * @example "https://api.example.com/v1"
+   * @example "https://{username}.example.com:{port}/{basePath}"
+   * @example "/v1"
+   */
+  url: string
+  
+  /** 
+   * An optional string describing the host designated by the URL. 
+   * CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "Development server"
+   * @example "Production server"
+   */
+  description?: string
+  
+  /** 
+   * A map between a variable name and its value. The value is used for substitution 
+   * in the server's URL template.
+   * 
+   * @example { username: { default: "demo" }, port: { default: "8080" } }
+   */
+  variables?: Record<string, ServerVariable>
+}
+
+/**
+ * -----
+ * Server Variable Object
+ * -----
+ *
+ * An object representing a Server Variable for server URL template substitution.
+ *
+ * The Server Variable Object represents a server variable for server URL template
+ * substitution. It can contain an enumeration of values, a default value, and
+ * a description.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#server-variable-object | OpenAPI 3.0.4 Server Variable} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#server-variable-object | OpenAPI 3.0.3 Server Variable} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#server-variable-object | OpenAPI 3.0.2 Server Variable} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#server-variable-object | OpenAPI 3.0.1 Server Variable} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#server-variable-object | OpenAPI 3.0.0 Server Variable} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set
+ * @key `default` - Required The default value to use for substitution
+ * @key `description` - Optional An optional description for the server variable
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `default` field is required. Unlike the Schema Object's default, this value MUST be provided by the consumer.
+ * In OpenAPI 3.0.1+, the `default` field was clarified to be the default value to use
+ * for substitution, and to send, if an alternate value is not supplied.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple variable):
+ * ```ts
+ * const variable: ServerVariable = {
+ *   default: "v2",
+ *   description: "API version"
+ * };
+ * ```
+ *
+ * @example (variable with enum):
+ * ```ts
+ * const variable: ServerVariable = {
+ *   enum: ["8443", "443"],
+ *   default: "8443",
+ *   description: "Port number"
+ * };
+ * ```
+ *
+ * @example (variable with extension):
+ * ```ts
+ * const variable: ServerVariable = {
+ *   default: "production",
+ *   description: "Environment",
+ *   "x-environment-type": "production"
+ * };
+ * ```
+ */
+export interface ServerVariable extends Extension {
+  /** 
+   * An enumeration of string values to be used if the substitution options are from a limited set.
+   * 
+   * @example ["8443", "443"]
+   * @example ["v1", "v2", "v3"]
+   */
+  enum?: string[]
+  
+  /** 
+   * The default value to use for substitution, and to send, if an alternate value is not supplied. 
+   * Unlike the Schema Object's default, this value MUST be provided by the consumer.
+   * 
+   * @example "demo"
+   * @example "8443"
+   * @example "v2"
+   */
+  default: string
+  
+  /** 
+   * An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "this value is assigned by the service provider"
+   * @example "Port number for the server"
+   */
+  description?: string
+}

versions/3.0.x/spec.ts

@@ -0,0 +1,200 @@
+import type { Extension } from "./extensions"
+
+// Import all the major component types
+import type { Info } from "./info"
+import type { 
+  PathItemObject, 
+  Operation, 
+  Parameter, 
+  Response, 
+  Header, 
+  RequestBody,
+  MediaType,
+  Encoding,
+  Callback,
+  Link,
+  Example
+} from "./paths"
+import type { 
+  Schema, 
+  Discriminator
+} from "./schema"
+import type { XML } from "./xml"
+import type { Components } from "./components"
+import type { 
+  Server,
+  ServerVariable
+} from "./servers"
+import type { Tag } from "./tags"
+import type { ExternalDocumentation } from "./external-documentation"
+import type { Reference } from "./references"
+import type { 
+  SecurityScheme,
+  SecurityRequirement
+} from "./security"
+
+/**
+ * -----
+ * OpenAPI Object
+ * -----
+ *
+ * Root OpenAPI 3.0 Schema (OpenAPI Object)
+ * 
+ * This is the root document object of the OpenAPI specification. It contains
+ * all the metadata about the API being described. This object is based on the
+ * JSON Schema Specification Wright Draft 00 and uses a predefined subset of it.
+ * 
+ * The OpenAPI Object is the root of the specification document and contains
+ * all the information about the API, including its metadata, available paths,
+ * data models, security schemes, and more.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 OpenAPI Object} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 OpenAPI Object} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 OpenAPI Object} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 OpenAPI Object} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 OpenAPI Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `openapi` - Required Specifies the OpenAPI specification version
+ * @key `info` - Required Provides metadata about the API
+ * @key `servers` - Optional An array of Server Objects
+ * @key `paths` - Required The available paths and operations for the API
+ * @key `components` - Optional An element to hold various schemas
+ * @key `security` - Optional A declaration of security mechanisms
+ * @key `tags` - Optional A list of tags used by the specification
+ * @key `externalDocs` - Optional Additional external documentation
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `openapi` field is required and must be "3.0.0" for this specification.
+ * The `info` and `paths` fields are also required.
+ *
+ * -----
+ * Examples
+ * -----
+ * @example
+ * ```typescript
+ * const openapi: Specification = {
+ *   openapi: "3.0.0",
+ *   info: {
+ *     title: "Sample Pet Store App",
+ *     description: "This is a sample server for a pet store.",
+ *     version: "1.0.1"
+ *   },
+ *   servers: [
+ *     {
+ *       url: "https://petstore.swagger.io/v2",
+ *       description: "Petstore server"
+ *     }
+ *   ],
+ *   paths: {
+ *     "/pets": {
+ *       get: {
+ *         summary: "List all pets",
+ *         responses: {
+ *           "200": {
+ *             description: "A list of pets",
+ *             content: {
+ *               "application/json": {
+ *                 schema: {
+ *                   type: "array",
+ *                   items: { $ref: "#/components/schemas/Pet" }
+ *                 }
+ *               }
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   components: {
+ *     schemas: {
+ *       Pet: {
+ *         type: "object",
+ *         properties: {
+ *           id: { type: "integer", format: "int64" },
+ *           name: { type: "string" },
+ *           tag: { type: "string" }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type Specification = {
+  /** 
+   * Specifies the OpenAPI specification version being used. 
+   * Must be "3.0.0" for this specification.
+   */
+  openapi: "3.0.0"
+  
+  /** 
+   * Provides metadata about the API. The metadata can be used by the clients 
+   * if needed, and can be presented in the OpenAPI-UI for convenience.
+   */
+  info: Info
+  
+  /** 
+   * An array of Server Objects, which provide connectivity information to a target server. 
+   * If the servers property is not provided, or is an empty array, the default value 
+   * would be a Server Object with a url value of "/".
+   * 
+   * @example [{ url: "https://api.example.com/v1", description: "Production server" }]
+   * @example [{ url: "https://staging-api.example.com/v1", description: "Staging server" }]
+   */
+  servers?: Server[]
+  
+  /** 
+   * The available paths and operations for the API. This is the root of the 
+   * Path Item Object. It does not define a path or a basePath, they are defined 
+   * in the Paths Object. A relative path to an individual endpoint. The field 
+   * name MUST begin with a slash. The path is appended to the basePath in order 
+   * to construct the full URL. Path templating is allowed.
+   * 
+   * @example { "/users": { get: { ... } } }
+   * @example { "/users/{id}": { get: { ... } } }
+   */
+  paths: Record<string, PathItemObject>
+  
+  /** 
+   * An element to hold various schemas for the specification.
+   * 
+   * @example { schemas: { User: { type: "object", properties: { ... } } } }
+   */
+  components?: Components
+  
+  /** 
+   * A declaration of which security mechanisms can be used across the API. 
+   * The list of values includes alternative security requirement objects that can be used. 
+   * Only one of the security requirement objects need to be satisfied to authorize a request. 
+   * Individual operations can override this definition.
+   * 
+   * @example [{ "api_key": [] }]
+   * @example [{ "oauth2": ["read", "write"] }]
+   */
+  security?: SecurityRequirement[]
+  
+  /** 
+   * A list of tags used by the specification with additional metadata. 
+   * The order of the tags can be used to reflect on their order by the 
+   * parsing tools. Not all tags that are used by the Operation Object must 
+   * be declared. The tags that are not declared may be organized randomly 
+   * or based on the tools' logic. Each tag name in the list MUST be unique.
+   * 
+   * @example [{ name: "users", description: "User management" }]
+   */
+  tags?: Tag[]
+  
+  /** 
+   * Additional external documentation.
+   * 
+   * @example { description: "Find out more about our API", url: "https://example.com/docs" }
+   */
+  externalDocs?: ExternalDocumentation
+} & Extension

versions/3.0.x/tags.ts

@@ -0,0 +1,84 @@
+import type { Extension } from "./extensions"
+import type { ExternalDocumentation } from "./external-documentation"
+
+/**
+ * -----
+ * Tag Object
+ * -----
+ *
+ * Adds metadata to a single tag that is used by the Tag Object.
+ * It is not mandatory to have a Tag Object per tag used there.
+ *
+ * Tags provide a way to organize and categorize API operations, making it easier
+ * for developers to understand and navigate the API. They are commonly used to
+ * group operations by resource type, functionality, or any other logical division.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#tag-object | OpenAPI 3.0.4 Tag} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#tag-object | OpenAPI 3.0.3 Tag} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#tag-object | OpenAPI 3.0.2 Tag} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#tag-object | OpenAPI 3.0.1 Tag} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#tag-object | OpenAPI 3.0.0 Tag} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Required The name of the tag
+ * @key `description` - Optional A short description for the tag
+ * @key `externalDocs` - Optional Additional external documentation for this tag
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `name` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple tag):
+ * ```ts
+ * const tag: Tag = {
+ *   name: "users",
+ *   description: "User management operations"
+ * };
+ * ```
+ *
+ * @example (tag with external documentation):
+ * ```ts
+ * const tag: Tag = {
+ *   name: "pets",
+ *   description: "Pet store operations",
+ *   externalDocs: {
+ *     description: "Find out more about pet management",
+ *     url: "https://example.com/docs/pets"
+ *   }
+ * };
+ * ```
+ */
+export interface Tag extends Extension {
+  /** 
+   * The name of the tag. This field is required.
+   * 
+   * @example "users"
+   * @example "pets"
+   * @example "authentication"
+   */
+  name: string
+  
+  /** 
+   * A short description for the tag. CommonMark syntax MAY be used for rich text representation.
+   * 
+   * @example "User management operations"
+   * @example "Pet store operations"
+   */
+  description?: string
+  
+  /** 
+   * Additional external documentation for this tag.
+   * 
+   * @example { description: "Find out more about user management", url: "https://example.com/docs/users" }
+   */
+  externalDocs?: ExternalDocumentation
+}

versions/3.0.x/xml.ts

@@ -0,0 +1,91 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * XML Object
+ * -----
+ *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms) 
+ * and the name property should be used to add that information.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.0.4   | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML} |
+ * | 3.0.3   | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML} |
+ * | 3.0.2   | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML} |
+ * | 3.0.1   | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML} |
+ * | 3.0.0   | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Optional Replaces the name of the element/attribute used for the described schema property
+ * @key `namespace` - Optional The URL of the namespace definition
+ * @key `prefix` - Optional The prefix to be used for the name
+ * @key `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element
+ * @key `wrapped` - Optional MAY be used only for an array definition
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All fields are optional.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple XML):
+ * ```ts
+ * const xml: XML = {
+ *   name: "animal"
+ * };
+ * ```
+ */
+export interface XML extends Extension {
+  /** 
+   * Replaces the name of the element/attribute used for the described schema property.
+   * When defined within items, it will affect the name of the individual XML elements within the list.
+   * When defined alongside type being array (outside the items), it will affect the wrapping element
+   * and only if wrapped is true. If wrapped is false, it will affect the items within the array.
+   * 
+   * @example "animal"
+   * @example "item"
+   */
+  name?: string
+  
+  /** 
+   * The URL of the namespace definition. Value SHOULD be in the form of a URL.
+   * 
+   * @example "http://example.com/schema"
+   * @example "http://www.w3.org/XML/1998/namespace"
+   */
+  namespace?: string
+  
+  /** 
+   * The prefix to be used for the name.
+   * 
+   * @example "xs"
+   * @example "ns"
+   */
+  prefix?: string
+  
+  /** 
+   * Declares whether the property definition translates to an attribute instead of an element.
+   * Default value is false.
+   * 
+   * @example true
+   * @example false
+   */
+  attribute?: boolean
+  
+  /** 
+   * MAY be used only for an array definition. Signifies whether the array is wrapped (for example,
+   * <books><book/><book/></books>) or unwrapped (<book/><book/>). Default value is false.
+   * The definition takes effect only when defined alongside type being array (outside the items).
+   * 
+   * @example true
+   * @example false
+   */
+  wrapped?: boolean
+}

versions/3.1.x/components.ts

@@ -0,0 +1,134 @@
+import type { Extension } from "./extensions"
+import type { Reference } from "./references"
+import type { Schema } from "./schema"
+import type { Response, Parameter, Example, RequestBody, Header, Link, Callback, PathItemObject } from "./paths"
+import type { SecurityScheme } from "./security"
+
+/**
+ * -----
+ * Components Object
+ * -----
+ *
+ * Holds a set of reusable objects for different aspects of the OAS. All objects defined
+ * within the components object will have no effect on the API unless they are explicitly
+ * referenced from properties outside the components object.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#components-object | OpenAPI 3.1.0 Components Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `schemas` - An object to hold reusable Schema Objects
+ * @key `responses` - An object to hold reusable Response Objects
+ * @key `parameters` - An object to hold reusable Parameter Objects
+ * @key `examples` - An object to hold reusable Example Objects
+ * @key `requestBodies` - An object to hold reusable Request Body Objects
+ * @key `headers` - An object to hold reusable Header Objects
+ * @key `securitySchemes` - An object to hold reusable Security Scheme Objects
+ * @key `links` - An object to hold reusable Link Objects
+ * @key `callbacks` - An object to hold reusable Callback Objects
+ * @key `pathItems` - An object to hold reusable Path Item Objects
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple components):
+ * ```ts
+ * const components: Components = {
+ *   schemas: {
+ *     User: {
+ *       type: "object",
+ *       properties: {
+ *         id: { type: "integer", format: "int64" },
+ *         name: { type: "string" }
+ *       }
+ *     }
+ *   },
+ *   responses: {
+ *     NotFound: {
+ *       description: "Resource not found"
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface Components extends Extension {
+  /**
+   * An object to hold reusable Schema Objects.
+   *
+   * @example { User: { type: "object", properties: { id: { type: "integer" } } } }
+   */
+  schemas?: Record<string, Schema | Reference>
+
+  /**
+   * An object to hold reusable Response Objects.
+   *
+   * @example { NotFound: { description: "Resource not found" } }
+   */
+  responses?: Record<string, Response | Reference>
+
+  /**
+   * An object to hold reusable Parameter Objects.
+   *
+   * @example { UserId: { name: "userId", in: "path", required: true, schema: { type: "string" } } }
+   */
+  parameters?: Record<string, Parameter | Reference>
+
+  /**
+   * An object to hold reusable Example Objects.
+   *
+   * @example { UserExample: { value: { id: 1, name: "John Doe" } } }
+   */
+  examples?: Record<string, Example | Reference>
+
+  /**
+   * An object to hold reusable Request Body Objects.
+   *
+   * @example { UserRequestBody: { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } }
+   */
+  requestBodies?: Record<string, RequestBody | Reference>
+
+  /**
+   * An object to hold reusable Header Objects.
+   *
+   * @example { RateLimit: { description: "Rate limit per hour", schema: { type: "integer" } } }
+   */
+  headers?: Record<string, Header | Reference>
+
+  /**
+   * An object to hold reusable Security Scheme Objects.
+   *
+   * @example { ApiKeyAuth: { type: "apiKey", in: "header", name: "X-API-KEY" } }
+   */
+  securitySchemes?: Record<string, SecurityScheme | Reference>
+
+  /**
+   * An object to hold reusable Link Objects.
+   *
+   * @example { UserOrders: { operationId: "getOrdersByUserId", parameters: { userId: "$response.body#/id" } } }
+   */
+  links?: Record<string, Link | Reference>
+
+  /**
+   * An object to hold reusable Callback Objects.
+   *
+   * @example { UserCreatedCallback: { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "User created event" } } } } }
+   */
+  callbacks?: Record<string, Callback | Reference>
+
+  /**
+   * An object to hold reusable Path Item Objects.
+   *
+   * @example { UserPath: { get: { summary: "Get user by ID" } } }
+   */
+  pathItems?: Record<string, PathItemObject | Reference>
+}

versions/3.1.x/data-types/array.ts

@@ -0,0 +1,202 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Array Schema
+ * -----
+ *
+ * A schema for array values. Includes array-specific validation properties
+ * that are only valid when `type: "array"` is specified.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type: "array"` - Required The type identifier for array schemas
+ * @key `items` - Optional Schema for array items
+ * @key `prefixItems` - Optional Schema for array items at specific positions
+ * @key `contains` - Optional Schema that array must contain at least one item matching
+ * @key `minContains` - Optional Minimum number of items that must match contains
+ * @key `maxContains` - Optional Maximum number of items that must match contains
+ * @key `minItems` - Optional Minimum number of items in the array
+ * @key `maxItems` - Optional Maximum number of items in the array
+ * @key `uniqueItems` - Optional Whether array items must be unique
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All validation properties are optional. The `type` field must be "array".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic array):
+ * ```ts
+ * const arraySchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string" }
+ * };
+ * ```
+ *
+ * @example (array with validation):
+ * ```ts
+ * const arraySchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   minItems: 1,
+ *   maxItems: 10,
+ *   uniqueItems: true
+ * };
+ * ```
+ *
+ * @example (array with prefixItems):
+ * ```ts
+ * const arraySchema: ArraySchema = {
+ *   type: "array",
+ *   prefixItems: [
+ *     { type: "string" },
+ *     { type: "number" }
+ *   ]
+ * };
+ * ```
+ *
+ * @example (array with contains):
+ * ```ts
+ * const arraySchema: ArraySchema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   contains: { type: "string", enum: ["admin"] },
+ *   minContains: 1
+ * };
+ * ```
+ */
+export interface ArraySchema extends Extension {
+  /**
+   * The type identifier for array schemas.
+   * Must be "array".
+   */
+  type: "array"
+
+  /**
+   * The schema for array items.
+   * All items in the array must conform to this schema.
+   *
+   * Example: `{ type: "string" }`
+   */
+  items?: unknown
+
+  /**
+   * The schema for array items at specific positions.
+   * Items at position i must conform to the schema at index i.
+   *
+   * Example: `[{ type: "string" }, { type: "number" }]`
+   */
+  prefixItems?: unknown[]
+
+  /**
+   * The schema that the array must contain at least one item matching.
+   * At least one item in the array must conform to this schema.
+   *
+   * Example: `{ type: "string", enum: ["admin"] }`
+   */
+  contains?: unknown
+
+  /**
+   * The minimum number of items that must match the contains schema.
+   * Must be a non-negative integer.
+   *
+   * Example: `1`
+   */
+  minContains?: number
+
+  /**
+   * The maximum number of items that must match the contains schema.
+   * Must be a non-negative integer.
+   *
+   * Example: `5`
+   */
+  maxContains?: number
+
+  /**
+   * The minimum number of items in the array.
+   * Must be a non-negative integer.
+   *
+   * Example: `1`
+   */
+  minItems?: number
+
+  /**
+   * The maximum number of items in the array.
+   * Must be a non-negative integer.
+   *
+   * Example: `10`
+   */
+  maxItems?: number
+
+  /**
+   * Whether array items must be unique.
+   * If true, all items in the array must be unique.
+   *
+   * Example: `true`
+   */
+  uniqueItems?: boolean
+
+  /**
+   * An array of allowed values for the array.
+   * The value must be one of the values in this array.
+   *
+   * Example: `[["a", "b"], ["c", "d"]]`
+   */
+  enum?: unknown[]
+
+  /**
+   * A single allowed value for the array.
+   * The value must be exactly this value.
+   *
+   * Example: `["a", "b"]`
+   */
+  const?: unknown
+
+  /**
+   * An array of example values for the array.
+   * These are for documentation purposes only.
+   *
+   * Example: `[["a", "b"], ["c", "d"]]`
+   */
+  examples?: unknown[]
+
+  /**
+   * The default value for the array.
+   * This value will be used if no value is provided.
+   *
+   * Example: `[]`
+   */
+  default?: unknown[]
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"User Tags"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"Array of user tags"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/boolean.ts

@@ -0,0 +1,121 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Boolean Schema
+ * -----
+ *
+ * A schema for boolean values. Includes common validation properties
+ * that are only valid when `type: "boolean"` is specified.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type: "boolean"` - Required The type identifier for boolean schemas
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All validation properties are optional. The `type` field must be "boolean".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic boolean):
+ * ```ts
+ * const booleanSchema: BooleanSchema = {
+ *   type: "boolean"
+ * };
+ * ```
+ *
+ * @example (boolean with default):
+ * ```ts
+ * const booleanSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   default: false
+ * };
+ * ```
+ *
+ * @example (boolean with enum):
+ * ```ts
+ * const booleanSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   enum: [true, false]
+ * };
+ * ```
+ *
+ * @example (boolean with const):
+ * ```ts
+ * const booleanSchema: BooleanSchema = {
+ *   type: "boolean",
+ *   const: true
+ * };
+ * ```
+ */
+export interface BooleanSchema extends Extension {
+  /**
+   * The type identifier for boolean schemas.
+   * Must be "boolean".
+   */
+  type: "boolean"
+
+  /**
+   * An array of allowed values for the boolean.
+   * The value must be one of the values in this array.
+   *
+   * Example: `[true, false]`
+   */
+  enum?: boolean[]
+
+  /**
+   * A single allowed value for the boolean.
+   * The value must be exactly this value.
+   *
+   * Example: `true`
+   */
+  const?: boolean
+
+  /**
+   * An array of example values for the boolean.
+   * These are for documentation purposes only.
+   *
+   * Example: `[true, false]`
+   */
+  examples?: boolean[]
+
+  /**
+   * The default value for the boolean.
+   * This value will be used if no value is provided.
+   *
+   * Example: `false`
+   */
+  default?: boolean
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"Is Active"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"Whether the user is active"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/composition.ts

@@ -0,0 +1,189 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Composition Schema
+ * -----
+ *
+ * A schema that uses composition keywords (allOf, anyOf, oneOf, not).
+ * These keywords are mutually exclusive with $ref, but otherwise can
+ * appear with any validation keywords. This schema type supports
+ * advanced JSON Schema 2020-12 features like conditional schemas.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `allOf` - Optional Array of schemas that must all be satisfied
+ * @key `anyOf` - Optional Array of schemas where at least one must be satisfied
+ * @key `oneOf` - Optional Array of schemas where exactly one must be satisfied
+ * @key `not` - Optional Schema that must not be satisfied
+ * @key `if` - Optional Schema for conditional validation
+ * @key `then` - Optional Schema to apply if if condition is met
+ * @key `else` - Optional Schema to apply if if condition is not met
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * Composition keywords are mutually exclusive with $ref. At least one composition
+ * keyword must be present. The `if`/`then`/`else` keywords work together for
+ * conditional validation.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (allOf composition):
+ * ```ts
+ * const compositionSchema: CompositionSchema = {
+ *   allOf: [
+ *     { type: "object", properties: { name: { type: "string" } } },
+ *     { type: "object", properties: { age: { type: "number" } } }
+ *   ]
+ * };
+ * ```
+ *
+ * @example (anyOf composition):
+ * ```ts
+ * const compositionSchema: CompositionSchema = {
+ *   anyOf: [
+ *     { type: "string" },
+ *     { type: "number" }
+ *   ]
+ * };
+ * ```
+ *
+ * @example (oneOf composition):
+ * ```ts
+ * const compositionSchema: CompositionSchema = {
+ *   oneOf: [
+ *     { type: "string", enum: ["active"] },
+ *     { type: "string", enum: ["inactive"] }
+ *   ]
+ * };
+ * ```
+ *
+ * @example (conditional schema):
+ * ```ts
+ * const compositionSchema: CompositionSchema = {
+ *   if: { type: "object", properties: { type: { const: "user" } } },
+ *   then: { type: "object", properties: { name: { type: "string" } } },
+ *   else: { type: "object", properties: { id: { type: "string" } } }
+ * };
+ * ```
+ */
+export interface CompositionSchema extends Extension {
+  /**
+   * An array of schemas that must all be satisfied.
+   * The value must conform to all schemas in the array.
+   *
+   * Example: `[{ type: "object" }, { properties: { name: { type: "string" } } }]`
+   */
+  allOf?: unknown[]
+
+  /**
+   * An array of schemas where at least one must be satisfied.
+   * The value must conform to at least one schema in the array.
+   *
+   * Example: `[{ type: "string" }, { type: "number" }]`
+   */
+  anyOf?: unknown[]
+
+  /**
+   * An array of schemas where exactly one must be satisfied.
+   * The value must conform to exactly one schema in the array.
+   *
+   * Example: `[{ type: "string" }, { type: "number" }]`
+   */
+  oneOf?: unknown[]
+
+  /**
+   * A schema that must not be satisfied.
+   * The value must not conform to this schema.
+   *
+   * Example: `{ type: "string" }`
+   */
+  not?: unknown
+
+  /**
+   * A schema for conditional validation.
+   * Used with `then` and `else` for conditional logic.
+   *
+   * Example: `{ type: "object", properties: { type: { const: "user" } } }`
+   */
+  if?: unknown
+
+  /**
+   * A schema to apply if the `if` condition is met.
+   * The value must conform to this schema if the `if` schema is satisfied.
+   *
+   * Example: `{ type: "object", properties: { name: { type: "string" } } }`
+   */
+  then?: unknown
+
+  /**
+   * A schema to apply if the `if` condition is not met.
+   * The value must conform to this schema if the `if` schema is not satisfied.
+   *
+   * Example: `{ type: "object", properties: { id: { type: "string" } } }`
+   */
+  else?: unknown
+
+  /**
+   * An array of allowed values.
+   * The value must be one of the values in this array.
+   *
+   * Example: `["active", "inactive"]`
+   */
+  enum?: unknown[]
+
+  /**
+   * A single allowed value.
+   * The value must be exactly this value.
+   *
+   * Example: `"active"`
+   */
+  const?: unknown
+
+  /**
+   * An array of example values.
+   * These are for documentation purposes only.
+   *
+   * Example: `["example1", "example2"]`
+   */
+  examples?: unknown[]
+
+  /**
+   * The default value.
+   * This value will be used if no value is provided.
+   *
+   * Example: `"default"`
+   */
+  default?: unknown
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"Composed Schema"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"A schema composed of multiple schemas"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/index.ts

@@ -0,0 +1,8 @@
+export type { ReferenceSchema } from "./reference"
+export type { StringSchema } from "./string"
+export type { NumberSchema } from "./number"
+export type { IntegerSchema } from "./integer"
+export type { BooleanSchema } from "./boolean"
+export type { ArraySchema } from "./array"
+export type { ObjectSchema } from "./object"
+export type { CompositionSchema } from "./composition"

versions/3.1.x/data-types/integer.ts

@@ -0,0 +1,178 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Integer Schema
+ * -----
+ *
+ * A schema for integer values. Includes integer-specific validation properties
+ * that are only valid when `type: "integer"` is specified.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type: "integer"` - Required The type identifier for integer schemas
+ * @key `format` - Optional The format of the integer
+ * @key `multipleOf` - Optional Integer must be a multiple of this value
+ * @key `maximum` - Optional Maximum value (inclusive)
+ * @key `minimum` - Optional Minimum value (inclusive)
+ * @key `exclusiveMaximum` - Optional Maximum value (exclusive)
+ * @key `exclusiveMinimum` - Optional Minimum value (exclusive)
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All validation properties are optional. The `type` field must be "integer".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic integer):
+ * ```ts
+ * const integerSchema: IntegerSchema = {
+ *   type: "integer"
+ * };
+ * ```
+ *
+ * @example (integer with format and validation):
+ * ```ts
+ * const integerSchema: IntegerSchema = {
+ *   type: "integer",
+ *   format: "int32",
+ *   minimum: 0,
+ *   maximum: 100
+ * };
+ * ```
+ *
+ * @example (integer with multipleOf):
+ * ```ts
+ * const integerSchema: IntegerSchema = {
+ *   type: "integer",
+ *   multipleOf: 5
+ * };
+ * ```
+ *
+ * @example (integer with exclusive bounds):
+ * ```ts
+ * const integerSchema: IntegerSchema = {
+ *   type: "integer",
+ *   exclusiveMinimum: 0,
+ *   exclusiveMaximum: 100
+ * };
+ * ```
+ */
+export interface IntegerSchema extends Extension {
+  /**
+   * The type identifier for integer schemas.
+   * Must be "integer".
+   */
+  type: "integer"
+
+  /**
+   * The format of the integer.
+   * See OpenAPI 3.1.x Data Type Formats for further details.
+   *
+   * Example: `"int32"`, `"int64"`
+   */
+  format?: string
+
+  /**
+   * The integer must be a multiple of this value.
+   * Must be a positive integer.
+   *
+   * Example: `5`
+   */
+  multipleOf?: number
+
+  /**
+   * The maximum value of the integer (inclusive).
+   * The integer must be less than or equal to this value.
+   *
+   * Example: `100`
+   */
+  maximum?: number
+
+  /**
+   * The minimum value of the integer (inclusive).
+   * The integer must be greater than or equal to this value.
+   *
+   * Example: `0`
+   */
+  minimum?: number
+
+  /**
+   * The maximum value of the integer (exclusive).
+   * The integer must be less than this value.
+   *
+   * Example: `100`
+   */
+  exclusiveMaximum?: number
+
+  /**
+   * The minimum value of the integer (exclusive).
+   * The integer must be greater than this value.
+   *
+   * Example: `0`
+   */
+  exclusiveMinimum?: number
+
+  /**
+   * An array of allowed values for the integer.
+   * The value must be one of the values in this array.
+   *
+   * Example: `[1, 2, 3, 4, 5]`
+   */
+  enum?: number[]
+
+  /**
+   * A single allowed value for the integer.
+   * The value must be exactly this value.
+   *
+   * Example: `42`
+   */
+  const?: number
+
+  /**
+   * An array of example values for the integer.
+   * These are for documentation purposes only.
+   *
+   * Example: `[1, 2, 3]`
+   */
+  examples?: number[]
+
+  /**
+   * The default value for the integer.
+   * This value will be used if no value is provided.
+   *
+   * Example: `0`
+   */
+  default?: number
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"User ID"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"The unique identifier of the user"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/number.ts

@@ -0,0 +1,178 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Number Schema
+ * -----
+ *
+ * A schema for number values. Includes number-specific validation properties
+ * that are only valid when `type: "number"` is specified.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type: "number"` - Required The type identifier for number schemas
+ * @key `format` - Optional The format of the number
+ * @key `multipleOf` - Optional Number must be a multiple of this value
+ * @key `maximum` - Optional Maximum value (inclusive)
+ * @key `minimum` - Optional Minimum value (inclusive)
+ * @key `exclusiveMaximum` - Optional Maximum value (exclusive)
+ * @key `exclusiveMinimum` - Optional Minimum value (exclusive)
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All validation properties are optional. The `type` field must be "number".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic number):
+ * ```ts
+ * const numberSchema: NumberSchema = {
+ *   type: "number"
+ * };
+ * ```
+ *
+ * @example (number with format and validation):
+ * ```ts
+ * const numberSchema: NumberSchema = {
+ *   type: "number",
+ *   format: "float",
+ *   minimum: 0,
+ *   maximum: 100
+ * };
+ * ```
+ *
+ * @example (number with multipleOf):
+ * ```ts
+ * const numberSchema: NumberSchema = {
+ *   type: "number",
+ *   multipleOf: 0.5
+ * };
+ * ```
+ *
+ * @example (number with exclusive bounds):
+ * ```ts
+ * const numberSchema: NumberSchema = {
+ *   type: "number",
+ *   exclusiveMinimum: 0,
+ *   exclusiveMaximum: 100
+ * };
+ * ```
+ */
+export interface NumberSchema extends Extension {
+  /**
+   * The type identifier for number schemas.
+   * Must be "number".
+   */
+  type: "number"
+
+  /**
+   * The format of the number.
+   * See OpenAPI 3.1.x Data Type Formats for further details.
+   *
+   * Example: `"float"`, `"double"`
+   */
+  format?: string
+
+  /**
+   * The number must be a multiple of this value.
+   * Must be a positive number.
+   *
+   * Example: `0.5`
+   */
+  multipleOf?: number
+
+  /**
+   * The maximum value of the number (inclusive).
+   * The number must be less than or equal to this value.
+   *
+   * Example: `100`
+   */
+  maximum?: number
+
+  /**
+   * The minimum value of the number (inclusive).
+   * The number must be greater than or equal to this value.
+   *
+   * Example: `0`
+   */
+  minimum?: number
+
+  /**
+   * The maximum value of the number (exclusive).
+   * The number must be less than this value.
+   *
+   * Example: `100`
+   */
+  exclusiveMaximum?: number
+
+  /**
+   * The minimum value of the number (exclusive).
+   * The number must be greater than this value.
+   *
+   * Example: `0`
+   */
+  exclusiveMinimum?: number
+
+  /**
+   * An array of allowed values for the number.
+   * The value must be one of the values in this array.
+   *
+   * Example: `[1, 2, 3, 4, 5]`
+   */
+  enum?: number[]
+
+  /**
+   * A single allowed value for the number.
+   * The value must be exactly this value.
+   *
+   * Example: `42`
+   */
+  const?: number
+
+  /**
+   * An array of example values for the number.
+   * These are for documentation purposes only.
+   *
+   * Example: `[1.5, 2.7, 3.14]`
+   */
+  examples?: number[]
+
+  /**
+   * The default value for the number.
+   * This value will be used if no value is provided.
+   *
+   * Example: `0`
+   */
+  default?: number
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"Price"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"The price of the item"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/object.ts

@@ -0,0 +1,217 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Object Schema
+ * -----
+ *
+ * A schema for object values. Includes object-specific validation properties
+ * that are only valid when `type: "object"` is specified.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type: "object"` - Required The type identifier for object schemas
+ * @key `properties` - Optional Map of property names to their schemas
+ * @key `required` - Optional Array of required property names
+ * @key `additionalProperties` - Optional Schema for additional properties
+ * @key `patternProperties` - Optional Map of regex patterns to schemas
+ * @key `propertyNames` - Optional Schema for property names
+ * @key `minProperties` - Optional Minimum number of properties
+ * @key `maxProperties` - Optional Maximum number of properties
+ * @key `dependentRequired` - Optional Map of property names to arrays of required properties
+ * @key `dependentSchemas` - Optional Map of property names to schemas
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All validation properties are optional. The `type` field must be "object".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic object):
+ * ```ts
+ * const objectSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "number" }
+ *   }
+ * };
+ * ```
+ *
+ * @example (object with required properties):
+ * ```ts
+ * const objectSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "number" }
+ *   },
+ *   required: ["name"]
+ * };
+ * ```
+ *
+ * @example (object with additionalProperties):
+ * ```ts
+ * const objectSchema: ObjectSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" }
+ *   },
+ *   additionalProperties: { type: "string" }
+ * };
+ * ```
+ *
+ * @example (object with patternProperties):
+ * ```ts
+ * const objectSchema: ObjectSchema = {
+ *   type: "object",
+ *   patternProperties: {
+ *     "^S_": { type: "string" }
+ *   }
+ * };
+ * ```
+ */
+export interface ObjectSchema extends Extension {
+  /**
+   * The type identifier for object schemas.
+   * Must be "object".
+   */
+  type: "object"
+
+  /**
+   * A map of property names to their schemas.
+   * Each property in the object must conform to its corresponding schema.
+   *
+   * Example: `{ name: { type: "string" }, age: { type: "number" } }`
+   */
+  properties?: Record<string, unknown>
+
+  /**
+   * An array of required property names.
+   * These properties must be present in the object.
+   *
+   * Example: `["name", "email"]`
+   */
+  required?: string[]
+
+  /**
+   * The schema for additional properties not defined in properties.
+   * If false, no additional properties are allowed.
+   * If true, any additional properties are allowed.
+   * If a schema, additional properties must conform to this schema.
+   *
+   * Example: `{ type: "string" }` or `false` or `true`
+   */
+  additionalProperties?: unknown | boolean
+
+  /**
+   * A map of regex patterns to schemas.
+   * Properties whose names match a pattern must conform to the corresponding schema.
+   *
+   * Example: `{ "^S_": { type: "string" } }`
+   */
+  patternProperties?: Record<string, unknown>
+
+  /**
+   * The schema for property names.
+   * All property names in the object must conform to this schema.
+   *
+   * Example: `{ type: "string", pattern: "^[A-Za-z][A-Za-z0-9]*$" }`
+   */
+  propertyNames?: unknown
+
+  /**
+   * The minimum number of properties in the object.
+   * Must be a non-negative integer.
+   *
+   * Example: `1`
+   */
+  minProperties?: number
+
+  /**
+   * The maximum number of properties in the object.
+   * Must be a non-negative integer.
+   *
+   * Example: `10`
+   */
+  maxProperties?: number
+
+  /**
+   * A map of property names to arrays of required properties.
+   * If a property is present, the properties in its array must also be present.
+   *
+   * Example: `{ credit_card: ["billing_address"] }`
+   */
+  dependentRequired?: Record<string, string[]>
+
+  /**
+   * A map of property names to schemas.
+   * If a property is present, the object must conform to the corresponding schema.
+   *
+   * Example: `{ credit_card: { type: "object", properties: { number: { type: "string" } } } }`
+   */
+  dependentSchemas?: Record<string, unknown>
+
+  /**
+   * An array of allowed values for the object.
+   * The value must be one of the values in this array.
+   *
+   * Example: `[{ name: "John" }, { name: "Jane" }]`
+   */
+  enum?: Record<string, unknown>[]
+
+  /**
+   * A single allowed value for the object.
+   * The value must be exactly this value.
+   *
+   * Example: `{ name: "John" }`
+   */
+  const?: Record<string, unknown>
+
+  /**
+   * An array of example values for the object.
+   * These are for documentation purposes only.
+   *
+   * Example: `[{ name: "John", age: 30 }]`
+   */
+  examples?: Record<string, unknown>[]
+
+  /**
+   * The default value for the object.
+   * This value will be used if no value is provided.
+   *
+   * Example: `{}`
+   */
+  default?: Record<string, unknown>
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"User"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"A user object"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/reference.ts

@@ -0,0 +1,71 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * Reference Schema
+ * -----
+ *
+ * A schema that references another schema. When a schema contains `$ref`,
+ * no other sibling keys are allowed except `description` and extensions.
+ * This enforces the OpenAPI 3.1.x rule that `$ref` is exclusive with other properties.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#reference-object | OpenAPI 3.1.1 Reference Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#reference-object | OpenAPI 3.1.0 Reference Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `$ref` - Required A reference to a schema
+ * @key `description` - Optional A description of the referenced schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * When `$ref` is present, no other properties except `description` and extensions are allowed.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple reference):
+ * ```ts
+ * const reference: ReferenceSchema = {
+ *   $ref: "#/components/schemas/User"
+ * };
+ * ```
+ *
+ * @example (reference with description):
+ * ```ts
+ * const reference: ReferenceSchema = {
+ *   $ref: "#/components/schemas/User",
+ *   description: "Reference to a user schema"
+ * };
+ * ```
+ *
+ * @example (reference with extension):
+ * ```ts
+ * const reference: ReferenceSchema = {
+ *   $ref: "#/components/schemas/User",
+ *   "x-custom": "value"
+ * };
+ * ```
+ */
+export interface ReferenceSchema extends Extension {
+  /**
+   * A reference to a schema. This MUST be in the form of a URI.
+   * When present, no other properties except `description` and extensions are allowed.
+   *
+   * Example: `"#/components/schemas/User"`
+   */
+  $ref: string
+
+  /**
+   * A description of the referenced schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"Reference to a user schema"`
+   */
+  description?: string
+}

versions/3.1.x/data-types/string.ts

@@ -0,0 +1,159 @@
+import type { Extension } from "../extensions"
+
+/**
+ * -----
+ * String Schema
+ * -----
+ *
+ * A schema for string values. Includes string-specific validation properties
+ * that are only valid when `type: "string"` is specified.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type: "string"` - Required The type identifier for string schemas
+ * @key `format` - Optional The format of the string
+ * @key `maxLength` - Optional Maximum length of the string
+ * @key `minLength` - Optional Minimum length of the string
+ * @key `pattern` - Optional Regular expression pattern
+ * @key `enum` - Optional Array of allowed values
+ * @key `const` - Optional Single allowed value
+ * @key `examples` - Optional Array of example values
+ * @key `default` - Optional Default value
+ * @key `title` - Optional Short title for the schema
+ * @key `description` - Optional Description of the schema
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All validation properties are optional. The `type` field must be "string".
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic string):
+ * ```ts
+ * const stringSchema: StringSchema = {
+ *   type: "string"
+ * };
+ * ```
+ *
+ * @example (string with format and validation):
+ * ```ts
+ * const stringSchema: StringSchema = {
+ *   type: "string",
+ *   format: "email",
+ *   maxLength: 255,
+ *   minLength: 5
+ * };
+ * ```
+ *
+ * @example (string with enum):
+ * ```ts
+ * const stringSchema: StringSchema = {
+ *   type: "string",
+ *   enum: ["active", "inactive", "pending"]
+ * };
+ * ```
+ *
+ * @example (string with pattern):
+ * ```ts
+ * const stringSchema: StringSchema = {
+ *   type: "string",
+ *   pattern: "^[A-Za-z0-9]+$"
+ * };
+ * ```
+ */
+export interface StringSchema extends Extension {
+  /**
+   * The type identifier for string schemas.
+   * Must be "string".
+   */
+  type: "string"
+
+  /**
+   * The format of the string.
+   * See OpenAPI 3.1.x Data Type Formats for further details.
+   *
+   * Example: `"email"`, `"date-time"`, `"uuid"`
+   */
+  format?: string
+
+  /**
+   * The maximum length of the string.
+   * Must be a non-negative integer.
+   *
+   * Example: `255`
+   */
+  maxLength?: number
+
+  /**
+   * The minimum length of the string.
+   * Must be a non-negative integer.
+   *
+   * Example: `1`
+   */
+  minLength?: number
+
+  /**
+   * A regular expression pattern that the string must match.
+   * Should be a valid ECMA 262 regular expression.
+   *
+   * Example: `"^[A-Za-z0-9]+$"`
+   */
+  pattern?: string
+
+  /**
+   * An array of allowed values for the string.
+   * The value must be one of the values in this array.
+   *
+   * Example: `["active", "inactive", "pending"]`
+   */
+  enum?: string[]
+
+  /**
+   * A single allowed value for the string.
+   * The value must be exactly this value.
+   *
+   * Example: `"active"`
+   */
+  const?: string
+
+  /**
+   * An array of example values for the string.
+   * These are for documentation purposes only.
+   *
+   * Example: `["example@email.com", "test@domain.com"]`
+   */
+  examples?: string[]
+
+  /**
+   * The default value for the string.
+   * This value will be used if no value is provided.
+   *
+   * Example: `"default"`
+   */
+  default?: string
+
+  /**
+   * A short title for the schema.
+   * This is for documentation purposes only.
+   *
+   * Example: `"User Email"`
+   */
+  title?: string
+
+  /**
+   * A description of the schema.
+   * CommonMark syntax MAY be used for rich text representation.
+   *
+   * Example: `"The email address of the user"`
+   */
+  description?: string
+}

versions/3.1.x/extensions.ts

@@ -0,0 +1,63 @@
+/**
+ * -----
+ * Extension Interface
+ * -----
+ *
+ * The Extension interface provides a way to add custom properties to OpenAPI objects
+ * using the `x-` prefix. This allows for specification extensions that are not part
+ * of the core OpenAPI specification but can be used by tools and implementations
+ * to provide additional functionality.
+ *
+ * Specification Extensions (`x-*`) are always allowed on OpenAPI objects.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#specification-extensions | OpenAPI 3.1.1 Specification Extensions} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#specification-extensions | OpenAPI 3.1.0 Specification Extensions} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All extension properties must start with `x-` and can contain any valid JSON value.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple extension):
+ * ```ts
+ * const extended: Extension = {
+ *   "x-custom-property": "custom value",
+ *   "x-internal-id": 123
+ * };
+ * ```
+ *
+ * @example (complex extension):
+ * ```ts
+ * const extended: Extension = {
+ *   "x-codegen-settings": {
+ *     "packageName": "com.example.api",
+ *     "generateTests": true
+ *   },
+ *   "x-rate-limit": {
+ *     "requests": 1000,
+ *     "window": "1h"
+ *   }
+ * };
+ * ```
+ */
+export interface Extension {
+  /**
+   * Specification Extensions allow adding custom properties to OpenAPI objects.
+   * All extension properties must start with `x-` and can contain any valid JSON value.
+   *
+   * @example "x-custom-property"
+   * @example "x-internal-id"
+   * @example "x-codegen-settings"
+   */
+  [key: `x-${string}`]: unknown
+}

versions/3.1.x/externalDocs.ts

@@ -0,0 +1,63 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * External Documentation Object
+ * -----
+ *
+ * Allows referencing an external resource for extended documentation.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#external-documentation-object | OpenAPI 3.1.1 External Documentation Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#external-documentation-object | OpenAPI 3.1.0 External Documentation Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `description` - Optional A short description of the target documentation
+ * @key `url` - Required The URL for the target documentation
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `url` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple external docs):
+ * ```ts
+ * const externalDocs: ExternalDocumentation = {
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ *
+ * @example (external docs with description):
+ * ```ts
+ * const externalDocs: ExternalDocumentation = {
+ *   description: "Find out more about our API",
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ */
+export interface ExternalDocumentation extends Extension {
+  /**
+   * A short description of the target documentation. CommonMark syntax MAY be used
+   * for rich text representation.
+   *
+   * @example "Find out more about our API"
+   * @example "Additional documentation for this endpoint"
+   */
+  description?: string
+
+  /**
+   * The URL for the target documentation. This field is required and MUST be in the
+   * format of a URL.
+   *
+   * @example "https://example.com/docs"
+   * @example "https://docs.example.com/api"
+   */
+  url: string
+}

versions/3.1.x/index.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview OpenAPI 3.1.x TypeScript Type Definitions
+ * 
+ * This module provides comprehensive TypeScript type definitions for OpenAPI 3.1.x specifications.
+ * All types are fully documented with JSDoc comments and include links to the official OpenAPI
+ * specification documentation.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1.html | OpenAPI 3.1.1 Specification}
+ * @see {@link https://spec.openapis.org/oas/v3.1.0.html | OpenAPI 3.1.0 Specification}
+ * 
+ * @version 3.1.x
+ * @since 1.0.0
+ */
+
+/**
+ * Main OpenAPI specification document type.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#oas-document | OpenAPI 3.1.1 OAS Document}
+ */
+export type { Specification } from "./spec"
+
+/**
+ * Core extension and reference types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#specification-extensions | OpenAPI 3.1.1 Specification Extensions}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#reference-object | OpenAPI 3.1.1 Reference Object}
+ */
+export type { Extension } from "./extensions"
+export type { Reference } from "./references"
+
+/**
+ * API information and metadata types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#info-object | OpenAPI 3.1.1 Info Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#contact-object | OpenAPI 3.1.1 Contact Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#license-object | OpenAPI 3.1.1 License Object}
+ */
+export type { Info, Contact, License } from "./info"
+
+/**
+ * Server configuration types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#server-object | OpenAPI 3.1.1 Server Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#server-variable-object | OpenAPI 3.1.1 Server Variable Object}
+ */
+export type { Server, ServerVariable } from "./servers"
+
+/**
+ * Path and operation definition types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#paths-object | OpenAPI 3.1.1 Paths Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#path-item-object | OpenAPI 3.1.1 Path Item Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#operation-object | OpenAPI 3.1.1 Operation Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#parameter-object | OpenAPI 3.1.1 Parameter Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#request-body-object | OpenAPI 3.1.1 Request Body Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#responses-object | OpenAPI 3.1.1 Responses Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#response-object | OpenAPI 3.1.1 Response Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#header-object | OpenAPI 3.1.1 Header Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#media-type-object | OpenAPI 3.1.1 Media Type Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#encoding-object | OpenAPI 3.1.1 Encoding Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#example-object | OpenAPI 3.1.1 Example Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#link-object | OpenAPI 3.1.1 Link Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#callback-object | OpenAPI 3.1.1 Callback Object}
+ */
+export type {
+  Paths,
+  PathItemObject,
+  Operation,
+  Parameter,
+  RequestBody,
+  Responses,
+  Response,
+  Header,
+  MediaType,
+  Encoding,
+  Example,
+  Link,
+  Callback
+} from "./paths"
+
+/**
+ * Schema definition types based on JSON Schema Draft 2020-12.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object}
+ * @see {@link https://json-schema.org/draft/2020-12/json-schema-core.html | JSON Schema Draft 2020-12}
+ */
+export type {
+  Schema,
+  ReferenceSchema,
+  StringSchema,
+  NumberSchema,
+  IntegerSchema,
+  BooleanSchema,
+  ArraySchema,
+  ObjectSchema,
+  CompositionSchema,
+  Discriminator
+} from "./schema"
+
+/**
+ * Reusable component types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object}
+ */
+export type { Components } from "./components"
+
+/**
+ * Security scheme and authentication types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#security-scheme-object | OpenAPI 3.1.1 Security Scheme Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#oauth-flows-object | OpenAPI 3.1.1 OAuth Flows Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#oauth-flow-object | OpenAPI 3.1.1 OAuth Flow Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#security-requirement-object | OpenAPI 3.1.1 Security Requirement Object}
+ */
+export type {
+  SecurityScheme,
+  OAuthFlows,
+  OAuthFlow,
+  SecurityRequirement
+} from "./security"
+
+/**
+ * Utility and metadata types.
+ * 
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#tag-object | OpenAPI 3.1.1 Tag Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#external-documentation-object | OpenAPI 3.1.1 External Documentation Object}
+ * @see {@link https://spec.openapis.org/oas/v3.1.1#xml-object | OpenAPI 3.1.1 XML Object}
+ */
+export type { Tag } from "./tags"
+export type { ExternalDocumentation } from "./externalDocs"
+export type { XML } from "./xml"

versions/3.1.x/info.ts

@@ -0,0 +1,263 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Info Object
+ * -----
+ *
+ * The object provides metadata about the API. The metadata MAY be used by tooling
+ * as required. The object may be extended with Specification Extensions.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#info-object | OpenAPI 3.1.1 Info Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#info-object | OpenAPI 3.1.0 Info Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `title` - Required The title of the API
+ * @key `summary` - Optional A short summary of the API
+ * @key `description` - Optional A description of the API
+ * @key `termsOfService` - Optional A URL to the Terms of Service for the API
+ * @key `contact` - Optional The contact information for the exposed API
+ * @key `license` - Optional The license information for the exposed API
+ * @key `version` - Required The version of the OpenAPI document
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `title` and `version` fields are required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (minimal info):
+ * ```ts
+ * const info: Info = {
+ *   title: "Pet Store API",
+ *   version: "1.0.0"
+ * };
+ * ```
+ *
+ * @example (complete info):
+ * ```ts
+ * const info: Info = {
+ *   title: "Pet Store API",
+ *   summary: "A sample API that uses a petstore as an example",
+ *   description: "This is a sample server Petstore server.",
+ *   termsOfService: "http://example.com/terms/",
+ *   contact: {
+ *     name: "API Support",
+ *     url: "http://www.example.com/support",
+ *     email: "support@example.com"
+ *   },
+ *   license: {
+ *     name: "Apache 2.0",
+ *     url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+ *   },
+ *   version: "1.0.0"
+ * };
+ * ```
+ */
+export interface Info extends Extension {
+  /**
+   * The title of the API. This field is required.
+   *
+   * @example "Pet Store API"
+   * @example "User Management API"
+   */
+  title: string
+
+  /**
+   * A short summary of the API.
+   *
+   * @example "A sample API that uses a petstore as an example"
+   * @example "API for managing users and their data"
+   */
+  summary?: string
+
+  /**
+   * A description of the API. CommonMark syntax MAY be used for rich text representation.
+   *
+   * @example "This is a sample server Petstore server."
+   * @example "This API provides endpoints for user management, authentication, and data operations."
+   */
+  description?: string
+
+  /**
+   * A URL to the Terms of Service for the API. MUST be in the format of a URL.
+   *
+   * @example "http://example.com/terms/"
+   * @example "https://www.example.com/terms-of-service"
+   */
+  termsOfService?: string
+
+  /**
+   * The contact information for the exposed API.
+   *
+   * @example { name: "API Support", email: "support@example.com" }
+   */
+  contact?: Contact
+
+  /**
+   * The license information for the exposed API.
+   *
+   * @example { name: "Apache 2.0", url: "https://www.apache.org/licenses/LICENSE-2.0.html" }
+   */
+  license?: License
+
+  /**
+   * The version of the OpenAPI document. This field is required.
+   *
+   * @example "1.0.0"
+   * @example "2.1.3"
+   */
+  version: string
+}
+
+/**
+ * -----
+ * Contact Object
+ * -----
+ *
+ * Contact information for the exposed API.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#contact-object | OpenAPI 3.1.1 Contact Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#contact-object | OpenAPI 3.1.0 Contact Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Optional The identifying name of the contact person/organization
+ * @key `url` - Optional The URL pointing to the contact information
+ * @key `email` - Optional The email address of the contact person/organization
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All fields are optional.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple contact):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "API Support",
+ *   email: "support@example.com"
+ * };
+ * ```
+ *
+ * @example (complete contact):
+ * ```ts
+ * const contact: Contact = {
+ *   name: "API Support",
+ *   url: "http://www.example.com/support",
+ *   email: "support@example.com"
+ * };
+ * ```
+ */
+export interface Contact extends Extension {
+  /**
+   * The identifying name of the contact person/organization.
+   *
+   * @example "API Support"
+   * @example "Development Team"
+   */
+  name?: string
+
+  /**
+   * The URL pointing to the contact information. MUST be in the format of a URL.
+   *
+   * @example "http://www.example.com/support"
+   * @example "https://example.com/contact"
+   */
+  url?: string
+
+  /**
+   * The email address of the contact person/organization. MUST be in the format of an email address.
+   *
+   * @example "support@example.com"
+   * @example "dev@example.com"
+   */
+  email?: string
+}
+
+/**
+ * -----
+ * License Object
+ * -----
+ *
+ * License information for the exposed API.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#license-object | OpenAPI 3.1.1 License Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#license-object | OpenAPI 3.1.0 License Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Required The license name used for the API
+ * @key `identifier` - Optional An SPDX license expression for the API
+ * @key `url` - Optional A URL to the license used for the API
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `name` field is required. Either `identifier` or `url` should be specified.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (with URL):
+ * ```ts
+ * const license: License = {
+ *   name: "Apache 2.0",
+ *   url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+ * };
+ * ```
+ *
+ * @example (with identifier):
+ * ```ts
+ * const license: License = {
+ *   name: "Apache 2.0",
+ *   identifier: "Apache-2.0"
+ * };
+ * ```
+ */
+export interface License extends Extension {
+  /**
+   * The license name used for the API. This field is required.
+   *
+   * @example "Apache 2.0"
+   * @example "MIT"
+   * @example "GPL-3.0"
+   */
+  name: string
+
+  /**
+   * An SPDX license expression for the API. The `identifier` field is mutually
+   * exclusive of the `url` field.
+   *
+   * @example "Apache-2.0"
+   * @example "MIT"
+   * @example "GPL-3.0"
+   */
+  identifier?: string
+
+  /**
+   * A URL to the license used for the API. MUST be in the format of a URL.
+   * The `url` field is mutually exclusive of the `identifier` field.
+   *
+   * @example "https://www.apache.org/licenses/LICENSE-2.0.html"
+   * @example "https://opensource.org/licenses/MIT"
+   */
+  url?: string
+}

versions/3.1.x/references.ts

@@ -0,0 +1,85 @@
+/**
+ * -----
+ * Reference Object
+ * -----
+ *
+ * A simple object to allow referencing other components in the specification,
+ * internally and externally. The Reference Object is a special JSON object
+ * that allows you to reference other parts of the OpenAPI specification.
+ *
+ * The `$ref` keyword is used to reference other components, and when present,
+ * the Reference Object is the only property that should be present (except
+ * for `description` and specification extensions).
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#reference-object | OpenAPI 3.1.1 Reference Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#reference-object | OpenAPI 3.1.0 Reference Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `$ref` - Required The reference string
+ * @key `description` - Optional A description of the referenced object
+ * @key `summary` - Optional A short summary of the referenced object
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `$ref` field is required and must be a valid JSON Reference.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (internal reference):
+ * ```ts
+ * const reference: Reference = {
+ *   "$ref": "#/components/schemas/User"
+ * };
+ * ```
+ *
+ * @example (external reference):
+ * ```ts
+ * const reference: Reference = {
+ *   "$ref": "https://example.com/schemas/User.json"
+ * };
+ * ```
+ *
+ * @example (reference with description):
+ * ```ts
+ * const reference: Reference = {
+ *   "$ref": "#/components/schemas/User",
+ *   "description": "A user object containing user information"
+ * };
+ * ```
+ */
+export interface Reference {
+  /**
+   * The reference string. This field is required and must be a valid JSON Reference.
+   * It can reference internal components using `#/` or external resources using URLs.
+   *
+   * @example "#/components/schemas/User"
+   * @example "#/components/responses/NotFound"
+   * @example "https://example.com/schemas/User.json"
+   */
+  $ref: string
+
+  /**
+   * A description of the referenced object. This can be used to provide
+   * additional context about what the referenced object represents.
+   *
+   * @example "A user object containing user information"
+   * @example "Standard error response for not found resources"
+   */
+  description?: string
+
+  /**
+   * A short summary of the referenced object. This can be used to provide
+   * a brief overview of what the referenced object represents.
+   *
+   * @example "User schema"
+   * @example "Not found response"
+   */
+  summary?: string
+}

versions/3.1.x/schema.ts

@@ -0,0 +1,255 @@
+import type { Extension } from "./extensions"
+import type { Reference } from "./references"
+import type { XML } from "./xml"
+import type { ExternalDocumentation } from "./externalDocs"
+import type {
+  ReferenceSchema,
+  StringSchema,
+  NumberSchema,
+  IntegerSchema,
+  BooleanSchema,
+  ArraySchema,
+  ObjectSchema,
+  CompositionSchema,
+} from "./data-types"
+
+/**
+ * -----
+ * Discriminator Object
+ * -----
+ *
+ * The Discriminator Object is used to aid in serialization, deserialization, and validation.
+ * It can be used to differentiate between other schemas which may satisfy the payload description.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#discriminator-object | OpenAPI 3.1.1 Discriminator Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#discriminator-object | OpenAPI 3.1.0 Discriminator Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `propertyName` - Required The name of the property in the payload that will hold the discriminator value
+ * @key `mapping` - Optional An object to hold mappings between payload values and schema names or references
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (basic discriminator):
+ * ```ts
+ * const discriminator: Discriminator = {
+ *   propertyName: "petType"
+ * };
+ * ```
+ *
+ * @example (discriminator with mapping):
+ * ```ts
+ * const discriminator: Discriminator = {
+ *   propertyName: "petType",
+ *   mapping: {
+ *     dog: "#/components/schemas/Dog",
+ *     cat: "#/components/schemas/Cat"
+ *   }
+ * };
+ * ```
+ */
+export interface Discriminator extends Extension {
+  /**
+   * The name of the property in the payload that will hold the discriminator value.
+   * This property must be present in the payload.
+   *
+   * Example: `"petType"`
+   */
+  propertyName: string
+
+  /**
+   * An object to hold mappings between payload values and schema names or references.
+   * If not provided, the schema name will be used as the discriminator value.
+   *
+   * Example: `{ dog: "#/components/schemas/Dog", cat: "#/components/schemas/Cat" }`
+   */
+  mapping?: Record<string, string>
+}
+
+/**
+ * -----
+ * Schema Object
+ * -----
+ *
+ * The Schema Object allows the definition of input and output data types. These types
+ * can be objects, but also primitives and arrays. This object is an extended subset
+ * of the JSON Schema Specification Draft 2020-12.
+ *
+ * The Schema Object is a discriminated union that enforces mutual-exclusion and
+ * co-occurrence rules as specified in the OpenAPI 3.1.x specification.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} |
+ *
+ * -----
+ * Schema Types
+ * -----
+ *
+ * The Schema union includes the following types:
+ *
+ * **Reference Schema:**
+ * @key `$ref` - A reference to a schema (exclusive with other properties)
+ * @key `description` - A description of the referenced schema
+ *
+ * **String Schema:**
+ * @key `type: "string"` - The type identifier for string schemas
+ * @key `format` - The format of the string (email, date, uuid, etc.)
+ * @key `maxLength` - The maximum length of the string
+ * @key `minLength` - The minimum length of the string
+ * @key `pattern` - A regular expression pattern the string must match
+ * @key `enum` - An enumeration of string values
+ * @key `const` - A constant string value
+ *
+ * **Number Schema:**
+ * @key `type: "number"` - The type identifier for number schemas
+ * @key `format` - The format of the number (float, double)
+ * @key `multipleOf` - A number that must be a multiple of this value
+ * @key `maximum` - The maximum value (inclusive)
+ * @key `exclusiveMaximum` - The maximum value (exclusive)
+ * @key `minimum` - The minimum value (inclusive)
+ * @key `exclusiveMinimum` - The minimum value (exclusive)
+ * @key `enum` - An enumeration of number values
+ * @key `const` - A constant number value
+ *
+ * **Integer Schema:**
+ * @key `type: "integer"` - The type identifier for integer schemas
+ * @key `format` - The format of the integer (int32, int64)
+ * @key `multipleOf` - An integer that must be a multiple of this value
+ * @key `maximum` - The maximum value (inclusive)
+ * @key `exclusiveMaximum` - The maximum value (exclusive)
+ * @key `minimum` - The minimum value (inclusive)
+ * @key `exclusiveMinimum` - The minimum value (exclusive)
+ * @key `enum` - An enumeration of integer values
+ * @key `const` - A constant integer value
+ *
+ * **Boolean Schema:**
+ * @key `type: "boolean"` - The type identifier for boolean schemas
+ * @key `enum` - An enumeration of boolean values
+ * @key `const` - A constant boolean value
+ *
+ * **Array Schema:**
+ * @key `type: "array"` - The type identifier for array schemas
+ * @key `items` - The schema for array items
+ * @key `prefixItems` - The schema for array items at specific positions
+ * @key `contains` - The schema that array must contain at least one item matching
+ * @key `minContains` - The minimum number of items that must match contains
+ * @key `maxContains` - The maximum number of items that must match contains
+ * @key `minItems` - The minimum number of items in the array
+ * @key `maxItems` - The maximum number of items in the array
+ * @key `uniqueItems` - Whether array items must be unique
+ *
+ * **Object Schema:**
+ * @key `type: "object"` - The type identifier for object schemas
+ * @key `properties` - A map of property names to their schemas
+ * @key `required` - An array of required property names
+ * @key `additionalProperties` - The schema for additional properties
+ * @key `patternProperties` - A map of regex patterns to schemas
+ * @key `propertyNames` - The schema for property names
+ * @key `minProperties` - The minimum number of properties
+ * @key `maxProperties` - The maximum number of properties
+ * @key `dependentRequired` - A map of property names to arrays of required properties
+ * @key `dependentSchemas` - A map of property names to schemas
+ *
+ * **Composition Schema:**
+ * @key `allOf` - An array of schemas that must all be satisfied
+ * @key `anyOf` - An array of schemas where at least one must be satisfied
+ * @key `oneOf` - An array of schemas where exactly one must be satisfied
+ * @key `not` - A schema that must not be satisfied
+ * @key `if` - A schema for conditional validation
+ * @key `then` - A schema to apply if if condition is met
+ * @key `else` - A schema to apply if if condition is not met
+ *
+ * **Common Properties:**
+ * @key `title` - A short title for the schema
+ * @key `description` - A description of the schema
+ * @key `default` - The default value for the schema
+ * @key `examples` - An array of example values
+ * @key `enum` - An enumeration of allowed values
+ * @key `const` - A constant allowed value
+ * @key `discriminator` - A discriminator object for polymorphism
+ * @key `xml` - XML-specific metadata
+ * @key `externalDocs` - External documentation
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The Schema Object is a discriminated union that enforces mutual-exclusion and
+ * co-occurrence rules. When `$ref` is present, no other properties except
+ * `description` and extensions are allowed. Composition keywords are mutually
+ * exclusive with `$ref`.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (reference schema):
+ * ```ts
+ * const schema: Schema = {
+ *   $ref: "#/components/schemas/User"
+ * };
+ * ```
+ *
+ * @example (string schema):
+ * ```ts
+ * const schema: Schema = {
+ *   type: "string",
+ *   format: "email",
+ *   maxLength: 255
+ * };
+ * ```
+ *
+ * @example (object schema):
+ * ```ts
+ * const schema: Schema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "number" }
+ *   },
+ *   required: ["name"]
+ * };
+ * ```
+ *
+ * @example (composition schema):
+ * ```ts
+ * const schema: Schema = {
+ *   allOf: [
+ *     { type: "object", properties: { name: { type: "string" } } },
+ *     { type: "object", properties: { age: { type: "number" } } }
+ *   ]
+ * };
+ * ```
+ */
+export type Schema = 
+  | ReferenceSchema
+  | StringSchema
+  | NumberSchema
+  | IntegerSchema
+  | BooleanSchema
+  | ArraySchema
+  | ObjectSchema
+  | CompositionSchema
+
+// Re-export individual schema types for convenience
+export type {
+  ReferenceSchema,
+  StringSchema,
+  NumberSchema,
+  IntegerSchema,
+  BooleanSchema,
+  ArraySchema,
+  ObjectSchema,
+  CompositionSchema,
+} from "./data-types"

versions/3.1.x/security.ts

@@ -0,0 +1,358 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Security Scheme Object
+ * -----
+ *
+ * Defines a security scheme that can be used by the operations. Supported schemes
+ * are HTTP authentication, an API key (either as a header, a cookie parameter or
+ * as a query parameter), mutual TLS (use of a client certificate), OAuth2's common
+ * flows (implicit, password, client credentials and authorization code) as defined
+ * in RFC6749, and OpenID Connect Discovery.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#security-scheme-object | OpenAPI 3.1.1 Security Scheme Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#security-scheme-object | OpenAPI 3.1.0 Security Scheme Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `type` - Required The type of the security scheme
+ * @key `description` - Optional A short description for security scheme
+ * @key `name` - Optional The name of the header, query or cookie parameter to be used
+ * @key `in` - Optional The location of the API key
+ * @key `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header
+ * @key `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted
+ * @key `flows` - Optional An object containing configuration information for the flow types supported
+ * @key `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `type` field is required. Other fields depend on the security scheme type.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (API Key):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "apiKey",
+ *   name: "X-API-Key",
+ *   in: "header"
+ * };
+ * ```
+ *
+ * @example (HTTP Basic):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "http",
+ *   scheme: "basic"
+ * };
+ * ```
+ *
+ * @example (OAuth2):
+ * ```ts
+ * const securityScheme: SecurityScheme = {
+ *   type: "oauth2",
+ *   flows: {
+ *     authorizationCode: {
+ *       authorizationUrl: "https://example.com/oauth/authorize",
+ *       tokenUrl: "https://example.com/oauth/token",
+ *       scopes: {
+ *         "read:pets": "read your pets",
+ *         "write:pets": "modify pets in your account"
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface SecurityScheme extends Extension {
+  /**
+   * The type of the security scheme. This field is required.
+   *
+   * @example "apiKey"
+   * @example "http"
+   * @example "oauth2"
+   * @example "openIdConnect"
+   */
+  type: "apiKey" | "http" | "oauth2" | "openIdConnect"
+
+  /**
+   * A short description for security scheme. CommonMark syntax MAY be used
+   * for rich text representation.
+   *
+   * @example "API key authentication"
+   * @example "OAuth2 authentication with authorization code flow"
+   */
+  description?: string
+
+  /**
+   * The name of the header, query or cookie parameter to be used. This field
+   * is required for `apiKey` type.
+   *
+   * @example "X-API-Key"
+   * @example "api_key"
+   * @example "sessionId"
+   */
+  name?: string
+
+  /**
+   * The location of the API key. This field is required for `apiKey` type.
+   *
+   * @example "header"
+   * @example "query"
+   * @example "cookie"
+   */
+  in?: "query" | "header" | "cookie"
+
+  /**
+   * The name of the HTTP Authorization scheme to be used in the Authorization
+   * header. This field is required for `http` type.
+   *
+   * @example "basic"
+   * @example "bearer"
+   * @example "digest"
+   */
+  scheme?: string
+
+  /**
+   * A hint to the client to identify how the bearer token is formatted. Bearer
+   * tokens are usually generated by an authorization server, so this information
+   * is primarily for documentation purposes.
+   *
+   * @example "JWT"
+   * @example "Bearer"
+   */
+  bearerFormat?: string
+
+  /**
+   * An object containing configuration information for the flow types supported.
+   * This field is required for `oauth2` type.
+   *
+   * @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } }
+   */
+  flows?: OAuthFlows
+
+  /**
+   * OpenId Connect URL to discover OAuth2 configuration values. This MUST be
+   * in the form of a URL. This field is required for `openIdConnect` type.
+   *
+   * @example "https://example.com/.well-known/openid_configuration"
+   */
+  openIdConnectUrl?: string
+}
+
+/**
+ * -----
+ * OAuth Flows Object
+ * -----
+ *
+ * Allows configuration of the supported OAuth Flows.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flows-object | OpenAPI 3.1.1 OAuth Flows Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flows-object | OpenAPI 3.1.0 OAuth Flows Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `implicit` - Optional Configuration for the OAuth Implicit flow
+ * @key `password` - Optional Configuration for the OAuth Resource Owner Password flow
+ * @key `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow
+ * @key `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All fields are optional. At least one flow must be specified.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (authorization code flow):
+ * ```ts
+ * const oauthFlows: OAuthFlows = {
+ *   authorizationCode: {
+ *     authorizationUrl: "https://example.com/oauth/authorize",
+ *     tokenUrl: "https://example.com/oauth/token",
+ *     scopes: {
+ *       "read:pets": "read your pets",
+ *       "write:pets": "modify pets in your account"
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface OAuthFlows extends Extension {
+  /**
+   * Configuration for the OAuth Implicit flow.
+   *
+   * @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { "read:pets": "read your pets" } }
+   */
+  implicit?: OAuthFlow
+
+  /**
+   * Configuration for the OAuth Resource Owner Password flow.
+   *
+   * @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } }
+   */
+  password?: OAuthFlow
+
+  /**
+   * Configuration for the OAuth Client Credentials flow.
+   *
+   * @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } }
+   */
+  clientCredentials?: OAuthFlow
+
+  /**
+   * Configuration for the OAuth Authorization Code flow.
+   *
+   * @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } }
+   */
+  authorizationCode?: OAuthFlow
+}
+
+/**
+ * -----
+ * OAuth Flow Object
+ * -----
+ *
+ * Configuration details for a supported OAuth Flow.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flow-object | OpenAPI 3.1.1 OAuth Flow Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flow-object | OpenAPI 3.1.0 OAuth Flow Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `authorizationUrl` - Optional The authorization URL to be used for this flow
+ * @key `tokenUrl` - Optional The token URL to be used for this flow
+ * @key `refreshUrl` - Optional The URL to be used for obtaining refresh tokens
+ * @key `scopes` - Required The available scopes for the OAuth2 security scheme
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `scopes` field is required. Other fields depend on the flow type.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (authorization code flow):
+ * ```ts
+ * const oauthFlow: OAuthFlow = {
+ *   authorizationUrl: "https://example.com/oauth/authorize",
+ *   tokenUrl: "https://example.com/oauth/token",
+ *   scopes: {
+ *     "read:pets": "read your pets",
+ *     "write:pets": "modify pets in your account"
+ *   }
+ * };
+ * ```
+ */
+export interface OAuthFlow extends Extension {
+  /**
+   * The authorization URL to be used for this flow. This MUST be in the form of a URL.
+   * This field is required for `implicit` and `authorizationCode` flows.
+   *
+   * @example "https://example.com/oauth/authorize"
+   */
+  authorizationUrl?: string
+
+  /**
+   * The token URL to be used for this flow. This MUST be in the form of a URL.
+   * This field is required for `password`, `clientCredentials`, and `authorizationCode` flows.
+   *
+   * @example "https://example.com/oauth/token"
+   */
+  tokenUrl?: string
+
+  /**
+   * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+   *
+   * @example "https://example.com/oauth/refresh"
+   */
+  refreshUrl?: string
+
+  /**
+   * The available scopes for the OAuth2 security scheme. A map between the scope
+   * name and a short description for it. This field is required.
+   *
+   * @example { "read:pets": "read your pets", "write:pets": "modify pets in your account" }
+   */
+  scopes: Record<string, string>
+}
+
+/**
+ * -----
+ * Security Requirement Object
+ * -----
+ *
+ * Lists the required security schemes for execution of the operation. The name
+ * used for each property MUST correspond to a security scheme declared in the
+ * Security Schemes under the Components Object.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#security-requirement-object | OpenAPI 3.1.1 Security Requirement Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#security-requirement-object | OpenAPI 3.1.0 Security Requirement Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `{name}` - Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object
+ *
+ * @note
+ * The property names correspond to security scheme names. The values are arrays of scope names.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (API key):
+ * ```ts
+ * const securityRequirement: SecurityRequirement = {
+ *   "api_key": []
+ * };
+ * ```
+ *
+ * @example (OAuth2):
+ * ```ts
+ * const securityRequirement: SecurityRequirement = {
+ *   "petstore_auth": ["write:pets", "read:pets"]
+ * };
+ * ```
+ *
+ * @example (multiple schemes):
+ * ```ts
+ * const securityRequirement: SecurityRequirement = {
+ *   "api_key": [],
+ *   "petstore_auth": ["write:pets", "read:pets"]
+ * };
+ * ```
+ */
+export interface SecurityRequirement {
+  /**
+   * Each name MUST correspond to a security scheme which is declared in the
+   * Security Schemes under the Components Object. The value is an array of
+   * scope names required for the execution. For OAuth2, the scopes are the
+   * scopes required for the execution. For other security schemes, the array
+   * MUST be empty.
+   *
+   * @example []
+   * @example ["write:pets", "read:pets"]
+   */
+  [name: string]: string[]
+}

versions/3.1.x/servers.ts

@@ -0,0 +1,164 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Server Object
+ * -----
+ *
+ * An object representing a Server.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#server-object | OpenAPI 3.1.1 Server Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#server-object | OpenAPI 3.1.0 Server Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `url` - Required A URL to the target host
+ * @key `description` - Optional An optional string describing the host designated by the URL
+ * @key `variables` - Optional A map between a variable name and its value
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `url` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple server):
+ * ```ts
+ * const server: Server = {
+ *   url: "https://api.example.com/v1"
+ * };
+ * ```
+ *
+ * @example (server with variables):
+ * ```ts
+ * const server: Server = {
+ *   url: "https://{username}.gigantic-server.com:{port}/{basePath}",
+ *   description: "The production API server",
+ *   variables: {
+ *     username: {
+ *       default: "demo",
+ *       description: "this value is assigned by the service provider"
+ *     },
+ *     port: {
+ *       enum: ["8443", "443"],
+ *       default: "8443"
+ *     },
+ *     basePath: {
+ *       default: "v2"
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface Server extends Extension {
+  /**
+   * A URL to the target host. This URL supports Server Variables and MAY be relative,
+   * to indicate that the host location is relative to the location where the OpenAPI
+   * document is being served. Variable substitutions will be made when a variable
+   * is named in `{brackets}`.
+   *
+   * @example "https://api.example.com/v1"
+   * @example "https://{username}.gigantic-server.com:{port}/{basePath}"
+   * @example "/v1"
+   */
+  url: string
+
+  /**
+   * An optional string describing the host designated by the URL. CommonMark syntax
+   * MAY be used for rich text representation.
+   *
+   * @example "The production API server"
+   * @example "The staging API server"
+   */
+  description?: string
+
+  /**
+   * A map between a variable name and its value. The value is used for substitution
+   * in the server's URL template.
+   *
+   * @example { username: { default: "demo" }, port: { default: "8443" } }
+   */
+  variables?: Record<string, ServerVariable>
+}
+
+/**
+ * -----
+ * Server Variable Object
+ * -----
+ *
+ * An object representing a Server Variable for server URL template substitution.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#server-variable-object | OpenAPI 3.1.1 Server Variable Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#server-variable-object | OpenAPI 3.1.0 Server Variable Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set
+ * @key `default` - Required The default value to use for substitution
+ * @key `description` - Optional An optional description for the server variable
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `default` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple variable):
+ * ```ts
+ * const variable: ServerVariable = {
+ *   default: "demo"
+ * };
+ * ```
+ *
+ * @example (variable with enum):
+ * ```ts
+ * const variable: ServerVariable = {
+ *   enum: ["8443", "443"],
+ *   default: "8443",
+ *   description: "The port number"
+ * };
+ * ```
+ */
+export interface ServerVariable extends Extension {
+  /**
+   * An enumeration of string values to be used if the substitution options are
+   * from a limited set. The array SHOULD NOT be empty.
+   *
+   * @example ["8443", "443"]
+   * @example ["v1", "v2", "v3"]
+   */
+  enum?: string[]
+
+  /**
+   * The default value to use for substitution, which SHALL be sent if an alternate
+   * value is not supplied. Note this behavior is different than the Schema Object's
+   * treatment of default values, because in those cases parameter values are optional.
+   * If the enum is defined, the value SHOULD exist in the enum's values.
+   *
+   * @example "demo"
+   * @example "8443"
+   * @example "v1"
+   */
+  default: string
+
+  /**
+   * An optional description for the server variable. CommonMark syntax MAY be used
+   * for rich text representation.
+   *
+   * @example "this value is assigned by the service provider"
+   * @example "The port number"
+   */
+  description?: string
+}

versions/3.1.x/spec.ts

@@ -0,0 +1,208 @@
+import type { Extension } from "./extensions"
+import type { Info } from "./info"
+import type { Server } from "./servers"
+import type { Paths } from "./paths"
+import type { Components } from "./components"
+import type { SecurityRequirement } from "./security"
+import type { Tag } from "./tags"
+import type { ExternalDocumentation } from "./externalDocs"
+
+/**
+ * -----
+ * OpenAPI Specification
+ * -----
+ *
+ * This is the root object of the OpenAPI document. It contains all the information
+ * needed to describe an API, including metadata, servers, paths, components, and more.
+ *
+ * The OpenAPI Specification (OAS) defines a standard, language-agnostic interface
+ * to RESTful APIs which allows both humans and computers to discover and understand
+ * the capabilities of the service without access to source code, documentation, or
+ * through network traffic inspection.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#openapi-object | OpenAPI 3.1.1 OpenAPI Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#openapi-object | OpenAPI 3.1.0 OpenAPI Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `openapi` - Required The version number of the OpenAPI Specification
+ * @key `info` - Required Provides metadata about the API
+ * @key `jsonSchemaDialect` - Optional The default value for the $schema keyword within Schema Objects
+ * @key `servers` - Optional An array of Server Objects
+ * @key `paths` - Optional The available paths and operations for the API
+ * @key `webhooks` - Optional The incoming webhooks that MAY be received as part of this API
+ * @key `components` - Optional An element to hold various schemas for the document
+ * @key `security` - Optional A declaration of which security mechanisms can be used across the API
+ * @key `tags` - Optional A list of tags used by the document with additional metadata
+ * @key `externalDocs` - Optional Additional external documentation
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `openapi` and `info` fields are required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (minimal specification):
+ * ```ts
+ * const spec: Specification = {
+ *   openapi: "3.1.0",
+ *   info: {
+ *     title: "Pet Store API",
+ *     version: "1.0.0"
+ *   }
+ * };
+ * ```
+ *
+ * @example (complete specification):
+ * ```ts
+ * const spec: Specification = {
+ *   openapi: "3.1.0",
+ *   info: {
+ *     title: "Pet Store API",
+ *     summary: "A sample API that uses a petstore as an example",
+ *     description: "This is a sample server Petstore server.",
+ *     termsOfService: "http://example.com/terms/",
+ *     contact: {
+ *       name: "API Support",
+ *       url: "http://www.example.com/support",
+ *       email: "support@example.com"
+ *     },
+ *     license: {
+ *       name: "Apache 2.0",
+ *       url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+ *     },
+ *     version: "1.0.0"
+ *   },
+ *   servers: [
+ *     {
+ *       url: "https://api.example.com/v1",
+ *       description: "The production API server"
+ *     }
+ *   ],
+ *   paths: {
+ *     "/pets": {
+ *       "get": {
+ *         "summary": "List all pets",
+ *         "responses": {
+ *           "200": {
+ *             "description": "A list of pets"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   components: {
+ *     schemas: {
+ *       Pet: {
+ *         type: "object",
+ *         properties: {
+ *           id: { type: "integer", format: "int64" },
+ *           name: { type: "string" }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   tags: [
+ *     {
+ *       name: "pets",
+ *       description: "Pet store operations"
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export interface Specification extends Extension {
+  /**
+   * This string MUST be the version number of the OpenAPI Specification that the
+   * OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret
+   * the OpenAPI document. This is not related to the API `info.version` string.
+   * This field is required.
+   *
+   * @example "3.1.0"
+   * @example "3.1.1"
+   */
+  openapi: string
+
+  /**
+   * Provides metadata about the API. The metadata MAY be used by tooling as required.
+   * This field is required.
+   *
+   * @example { title: "Pet Store API", version: "1.0.0" }
+   */
+  info: Info
+
+  /**
+   * The default value for the `$schema` keyword within Schema Objects contained
+   * within this OAS document. This MUST be in the form of a URI.
+   *
+   * @example "https://json-schema.org/draft/2020-12/schema"
+   */
+  jsonSchemaDialect?: string
+
+  /**
+   * An array of Server Objects, which provide connectivity information to a target
+   * server. If the `servers` property is not provided, or is an empty array, the
+   * default value would be a Server Object with a `url` value of `/`.
+   *
+   * @example [{ url: "https://api.example.com/v1", description: "The production API server" }]
+   */
+  servers?: Server[]
+
+  /**
+   * The available paths and operations for the API.
+   *
+   * @example { "/pets": { "get": { "summary": "List all pets", "responses": { "200": { "description": "A list of pets" } } } } }
+   */
+  paths?: Paths
+
+  /**
+   * The incoming webhooks that MAY be received as part of this API and that the
+   * API consumer MAY choose to implement. Closely related to the `callbacks` feature,
+   * this section describes requests initiated other than by an API call, for example
+   * by an out of band registration.
+   *
+   * @example { "newPet": { "post": { "requestBody": { "description": "Information about a new pet" } } } }
+   */
+  webhooks?: Record<string, any> // Will be properly typed when webhook types are created
+
+  /**
+   * An element to hold various schemas for the document.
+   *
+   * @example { schemas: { Pet: { type: "object", properties: { id: { type: "integer" } } } } }
+   */
+  components?: Components
+
+  /**
+   * A declaration of which security mechanisms can be used across the API. The list
+   * of values includes alternative security requirement objects that can be used.
+   * Only one of the security requirement objects need to be satisfied to authorize
+   * a request. Individual operations can override this definition.
+   *
+   * @example [{ "api_key": [] }]
+   */
+  security?: SecurityRequirement[]
+
+  /**
+   * A list of tags used by the document with additional metadata. The order of the
+   * tags can be used to reflect on their order by the parsing tools. Not all tags
+   * that are used by the Operation Object must be declared. The tags that are not
+   * declared MAY be organized randomly or based on the tools' logic. Each tag name
+   * in the list MUST be unique.
+   *
+   * @example [{ name: "pets", description: "Pet store operations" }]
+   */
+  tags?: Tag[]
+
+  /**
+   * Additional external documentation.
+   *
+   * @example { description: "Find out more about our API", url: "https://example.com/docs" }
+   */
+  externalDocs?: ExternalDocumentation
+}

versions/3.1.x/tags.ts

@@ -0,0 +1,142 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * Tag Object
+ * -----
+ *
+ * Adds metadata to a single tag that is used by the Tag Object.
+ * It is not mandatory to have a Tag Object per tag used there.
+ *
+ * Tags provide a way to organize and categorize API operations, making it easier
+ * for developers to understand and navigate the API. They are commonly used to
+ * group operations by resource type, functionality, or any other logical division.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#tag-object | OpenAPI 3.1.1 Tag Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#tag-object | OpenAPI 3.1.0 Tag Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Required The name of the tag
+ * @key `description` - Optional A short description for the tag
+ * @key `externalDocs` - Optional Additional external documentation for this tag
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `name` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple tag):
+ * ```ts
+ * const tag: Tag = {
+ *   name: "users",
+ *   description: "User management operations"
+ * };
+ * ```
+ *
+ * @example (tag with external documentation):
+ * ```ts
+ * const tag: Tag = {
+ *   name: "pets",
+ *   description: "Pet store operations",
+ *   externalDocs: {
+ *     description: "Find out more about pet management",
+ *     url: "https://example.com/docs/pets"
+ *   }
+ * };
+ * ```
+ */
+export interface Tag extends Extension {
+  /**
+   * The name of the tag. This field is required.
+   *
+   * @example "users"
+   * @example "pets"
+   * @example "authentication"
+   */
+  name: string
+
+  /**
+   * A short description for the tag. CommonMark syntax MAY be used for rich text representation.
+   *
+   * @example "User management operations"
+   * @example "Pet store operations"
+   */
+  description?: string
+
+  /**
+   * Additional external documentation for this tag.
+   *
+   * @example { description: "Find out more about user management", url: "https://example.com/docs/users" }
+   */
+  externalDocs?: ExternalDocumentation
+}
+
+/**
+ * -----
+ * External Documentation Object
+ * -----
+ *
+ * Allows referencing an external resource for extended documentation.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#external-documentation-object | OpenAPI 3.1.1 External Documentation Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#external-documentation-object | OpenAPI 3.1.0 External Documentation Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `description` - Optional A short description of the target documentation
+ * @key `url` - Required The URL for the target documentation
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * The `url` field is required.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple external docs):
+ * ```ts
+ * const externalDocs: ExternalDocumentation = {
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ *
+ * @example (external docs with description):
+ * ```ts
+ * const externalDocs: ExternalDocumentation = {
+ *   description: "Find out more about our API",
+ *   url: "https://example.com/docs"
+ * };
+ * ```
+ */
+export interface ExternalDocumentation extends Extension {
+  /**
+   * A short description of the target documentation. CommonMark syntax MAY be used
+   * for rich text representation.
+   *
+   * @example "Find out more about our API"
+   * @example "Additional documentation for this endpoint"
+   */
+  description?: string
+
+  /**
+   * The URL for the target documentation. This field is required and MUST be in the
+   * format of a URL.
+   *
+   * @example "https://example.com/docs"
+   * @example "https://docs.example.com/api"
+   */
+  url: string
+}

versions/3.1.x/xml.ts

@@ -0,0 +1,117 @@
+import type { Extension } from "./extensions"
+
+/**
+ * -----
+ * XML Object
+ * -----
+ *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ *
+ * When using arrays, XML element names are not inferred (for singular/plural forms)
+ * and the `name` property SHOULD be used to add that information.
+ *
+ * | Version | Reference |
+ * |---|-----|
+ * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#xml-object | OpenAPI 3.1.1 XML Object} |
+ * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#xml-object | OpenAPI 3.1.0 XML Object} |
+ *
+ * -----
+ * Fields
+ * -----
+ *
+ * @key `name` - Optional Replaces the name of the element/attribute used for the described schema property
+ * @key `namespace` - Optional The URI of the namespace definition
+ * @key `prefix` - Optional The prefix to be used for the name
+ * @key `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element
+ * @key `wrapped` - Optional MAY be used only for an array definition. Signifies whether the array is wrapped
+ * @key `x-${string}` - Specification Extensions
+ *
+ * @note
+ * All fields are optional.
+ *
+ * -----
+ * Examples
+ * -----
+ *
+ * @example (simple XML):
+ * ```ts
+ * const xml: XML = {
+ *   name: "user"
+ * };
+ * ```
+ *
+ * @example (XML with namespace):
+ * ```ts
+ * const xml: XML = {
+ *   name: "user",
+ *   namespace: "http://example.com/schema/user",
+ *   prefix: "user"
+ * };
+ * ```
+ *
+ * @example (XML attribute):
+ * ```ts
+ * const xml: XML = {
+ *   name: "id",
+ *   attribute: true
+ * };
+ * ```
+ *
+ * @example (wrapped array):
+ * ```ts
+ * const xml: XML = {
+ *   name: "users",
+ *   wrapped: true
+ * };
+ * ```
+ */
+export interface XML extends Extension {
+  /**
+   * Replaces the name of the element/attribute used for the described schema property.
+   * When defined within the Items Object (items), it will affect the name of the individual
+   * XML elements within the list. When defined alongside type being array (outside the items),
+   * it will affect the wrapping element and only if wrapped is true. If wrapped is false,
+   * it will be ignored.
+   *
+   * @example "user"
+   * @example "id"
+   * @example "users"
+   */
+  name?: string
+
+  /**
+   * The URI of the namespace definition. This MUST be in the form of an absolute URI.
+   *
+   * @example "http://example.com/schema/user"
+   * @example "http://www.w3.org/XML/1998/namespace"
+   */
+  namespace?: string
+
+  /**
+   * The prefix to be used for the name.
+   *
+   * @example "user"
+   * @example "xml"
+   */
+  prefix?: string
+
+  /**
+   * Declares whether the property definition translates to an attribute instead of an element.
+   * Default value is false.
+   *
+   * @example true
+   * @example false
+   */
+  attribute?: boolean
+
+  /**
+   * MAY be used only for an array definition. Signifies whether the array is wrapped
+   * (for example, `<books><book/><book/></books>`) or unwrapped
+   * (for example, `<book/><book/>`). Default value is false. The definition takes effect
+   * only when defined alongside type being array (outside the items).
+   *
+   * @example true
+   * @example false
+   */
+  wrapped?: boolean
+}

versions/License.ts

@@ -0,0 +1,82 @@
+import { spdxLicenseList } from "./SPDXLicenseList"
+
+/**
+ * Generic helper for creating "open enums".
+ * 
+ * Provides IntelliSense suggestions for known values `T`,
+ * but still allows arbitrary strings without collapsing to plain `string`.
+ * 
+ * @template T - The known literal values (string union)
+ */
+type OpenEnum<T extends string> = T | (string & { __openEnum?: never })
+
+/** 
+ * Known license Names. 
+ * 
+ * SPDX License List from spdx-license-list npm package
+ * Imported here as const to provide richer types for the License type.
+ * @see {@link https://spdx.org/licenses/ | SPDX License List}
+ * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} 
+ */
+export type KnownLicenseNames =
+  typeof spdxLicenseList[keyof typeof spdxLicenseList]["name"]
+
+/** 
+ * Known license SPDX Identifiers. 
+ * 
+ * SPDX License List from spdx-license-list npm package
+ * Imported here as const to provide richer types for the License type.
+ * @see {@link https://spdx.org/licenses/ | SPDX License List}
+ * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package}
+ */
+export type KnownLicenseIdentifiers = keyof typeof spdxLicenseList
+
+/** 
+ * Known license SPDX URLs. 
+ * 
+ * SPDX License List from spdx-license-list npm package
+ * Imported here as const to provide richer types for the License type.
+ * @see {@link https://spdx.org/licenses/ | SPDX License List}
+ * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} 
+ */
+export type KnownLicenseURLs = {
+  [K in keyof typeof spdxLicenseList]:
+    typeof spdxLicenseList[K] extends { url: infer U }
+      ? U extends string
+        ? U
+        : never
+      : never
+}[keyof typeof spdxLicenseList]
+
+/** 
+ * Open enum of SPDX license names.
+ * Suggests all known license names, but also accepts custom strings. 
+ * 
+ * The SPDX License List is sourced from the spdx-license-list npm package
+ * Imported here as const to provide richer types for the License type.
+ * @see {@link https://spdx.org/licenses/ | SPDX License List}
+ * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} 
+ */
+export type LicenseName = OpenEnum<KnownLicenseNames>
+
+/** 
+ * Open enum of SPDX license identifiers.
+ * Suggests all known SPDX identifiers, but also accepts custom strings.
+ * 
+ * The SPDX License List is sourced from the spdx-license-list npm package
+ * Imported here as const to provide richer types for the License type.
+ * @see {@link https://spdx.org/licenses/ | SPDX License List}
+ * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} 
+ */
+export type LicenseIdentifier = OpenEnum<KnownLicenseIdentifiers>
+
+/** 
+ * Open enum of SPDX license URLs.
+ * Suggests all known license URLs, but also accepts custom strings.
+ * 
+ * The SPDX License List is sourced from the spdx-license-list npm package
+ * Imported here as const to provide richer types for the License type.
+ * @see {@link https://spdx.org/licenses/ | SPDX License List}
+ * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} 
+ */
+export type LicenseURL = OpenEnum<KnownLicenseURLs>