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/object.ts

@@ -0,0 +1,206 @@
+import type { Extension } from "../extensions";
+import type { Schema } from "../schema";
+
+/**
+ * -----
+ * 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
+ * -----
+ *
+ * @property `type` - Must be "object" for object schemas.
+ * @property `properties` - The properties of the object.
+ * @property `required` - A list of required properties.
+ * @property `additionalProperties` - Additional properties for the object.
+ * @property `allOf` - An array of schemas that this schema must validate against.
+ * @property `description` - A short description of the object schema.
+ * @property `title` - A short title for the object schema.
+ * @property `default` - Declares the default value for the object.
+ * @property `maxProperties` - Maximum number of properties in the object.
+ * @property `minProperties` - Minimum number of properties in the object.
+ * @property `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, Schema>; // 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 | Schema; // 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?: Schema[]; // 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;
+}