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

Universal OpenAPI to LLM function calling schemas. Transform any Swagger/OpenAPI document into type-safe schemas for OpenAI, Claude, Qwen, and more.

/**
 * 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}
 *
 * 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>;
    /** Whether the property is read-only. */
    readOnly?: boolean;
    /** Whether the property is write-only. */
    writeOnly?: boolean;
}
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 {};
}