@samchon/openapi/lib/structures/IJsonSchemaAttribute.d.mts

OpenAPI definitions and converters for 'typia' and 'nestia'.

/**
 * Common attributes for JSON schema types.
 *
 * `IJsonSchemaAttribute` is a common interface for all JSON schema
 * types supported in here `@samchon/openapi`. Here is the list of
 * affected JSON schema types in `@samchon/openapi`, and you can extend
 * the interface by declaring module augmentation.
 *
 * - {@link OpenApi.IJsonSchema}
 * - {@link OpenApiV3_1.IJsonSchema}
 * - {@link OpenApiV3.IJsonSchema}
 * - {@link SwaggerV2.IJsonSchema}
 * - {@link IChatGptSchema}
 * - {@link IClaudeSchema}
 * - {@link IGeminiSchema}
 * - {@link ILlmSchemaV3}
 * - {@link ILlmSchemaV3_1}
 *
 * For example, if you extend the `IJsonSchemaAttribute` interface
 * like below, every JSON schema types in `@samchon/openapi` will have
 * a new custom attribute `x-wrtn-placeholder`.
 *
 * Also, if you augment the nested type like
 * `IJsonSchemaAttribute.IString`, you can add the custom attribute
 * to every string types in the JSON schema. In the below example case,
 * every string types will have a new custom attribute
 * `x-wrtn-secret-key`.
 *
 * ```typescript
 * declare module "@samchon/openapi" {
 *   export interface IJsonSchemaAttribute {
 *     /// Placeholder value for frontend application
 *     ///
 *     /// Placeholder ia label shown in the input field as a hint.
 *     /// For example, when an email input field exists, the label
 *     /// value would be "Insert your email address here".
 *     "x-wrtn-placeholder"?: string;
 *   }
 *   export namespace IJsonSchemaAttribute {
 *     export interface IString {
 *       /// Secret key for the schema.
 *       ///
 *       /// `x-wrtn-secret-key` is a property means a secret key
 *       /// that is required for the target API endpoint calling.
 *       /// If the secret key is not filled, the API call would
 *       /// be failed.
 *       "x-wrtn-secret-key"?: string;
 *     }
 *   }
 * }
 * ```
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface IJsonSchemaAttribute {
    /**
     * Title of the schema.
     */
    title?: string;
    /**
     * Detailed description of the schema.
     */
    description?: string;
    /**
     * Whether the type is deprecated or not.
     */
    deprecated?: boolean;
    /**
     * Example value.
     */
    example?: any;
    /**
     * List of example values as key-value pairs.
     */
    examples?: Record<string, any>;
}
export declare namespace IJsonSchemaAttribute {
    /**
     * Common attributes for boolean types.
     */
    export interface IBoolean extends ISignificant<"boolean"> {
    }
    /**
     * Common attributes for integer types.
     */
    export interface IInteger extends ISignificant<"integer"> {
    }
    /**
     * Common attributes for number types.
     */
    export interface INumber extends ISignificant<"number"> {
    }
    /**
     * Common attributes for string types.
     */
    export interface IString extends ISignificant<"string"> {
    }
    /**
     * Common attributes for object types.
     */
    export interface IObject extends ISignificant<"object"> {
    }
    /**
     * Common attributes for array types.
     */
    export interface IArray extends ISignificant<"array"> {
    }
    /**
     * Common attributes for null types.
     */
    export interface INull extends ISignificant<"null"> {
    }
    /**
     * Common attributes for unknown types.
     */
    export interface IUnknown extends IJsonSchemaAttribute {
        /**
         * Type is never be defined.
         */
        type?: undefined;
    }
    /**
     * Significant attributes that can be applied to the most types.
     */
    interface ISignificant<Type extends string> extends IJsonSchemaAttribute {
        /**
         * Discriminator value of the type.
         */
        type: Type;
    }
    export {};
}