openapi-types/2.0.0/data-types/object.ts

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
}