Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions.

3.1/data-types/array.ts

@@ -0,0 +1,210 @@
+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
+ * -----
+ *
+ * @property `type: "array"` - Required The type identifier for array schemas
+ * @property `items` - Optional Schema for array items
+ * @property `prefixItems` - Optional Schema for array items at specific positions
+ * @property `contains` - Optional Schema that array must contain at least one item matching
+ * @property `minContains` - Optional Minimum number of items that must match contains
+ * @property `maxContains` - Optional Maximum number of items that must match contains
+ * @property `minItems` - Optional Minimum number of items in the array
+ * @property `maxItems` - Optional Maximum number of items in the array
+ * @property `uniqueItems` - Optional Whether array items must be unique
+ * @property `enum` - Optional Array of allowed values
+ * @property `const` - Optional Single allowed value
+ * @property `examples` - Optional Array of example values
+ * @property `default` - Optional Default value
+ * @property `title` - Optional Short title for the schema
+ * @property `description` - Optional Description of the schema
+ * @property `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 example value for the array.
+	 * This is for documentation purposes only.
+	 *
+	 * Example: `["a", "b"]`
+	 */
+	example?: 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;
+}