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.

2.0/data-types/array.ts

@@ -0,0 +1,161 @@
+import type { Extension } from "../extensions";
+import type { Schema } from "../schema";
+
+/**
+ * -----
+ * 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
+ * -----
+ *
+ * @property `type` - Must be "array" for array schemas.
+ * @property `items` - Required. Describes the type of items in the array.
+ * @property `description` - A short description of the array schema.
+ * @property `title` - A short title for the array schema.
+ * @property `default` - Declares the default value for the array.
+ * @property `maxItems` - Maximum number of items in the array.
+ * @property `minItems` - Minimum number of items in the array.
+ * @property `uniqueItems` - Whether all items in the array must be unique.
+ * @property `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: Schema; // 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;
+}