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
 * -----
 *
 * @property `type` - Must be "integer" for integer schemas.
 * @property `format` - The extending format for the integer type (e.g., "int32", "int64").
 * @property `description` - A short description of the integer schema.
 * @property `title` - A short title for the integer schema.
 * @property `default` - Declares the default value for the integer.
 * @property `multipleOf` - The integer must be a multiple of this value.
 * @property `maximum` - Maximum value for the integer.
 * @property `exclusiveMaximum` - Whether the maximum value is exclusive.
 * @property `minimum` - Minimum value for the integer.
 * @property `exclusiveMinimum` - Whether the minimum value is exclusive.
 * @property `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;
}