Add IJsonSchemaAttribute.

.github/workflows/website.yml

@@ -4,6 +4,7 @@ on:
     branches:
       - master
     paths:
+      - README.md
       - 'src/**'
       - 'website/**'
       - 'package.json'

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samchon/openapi",
-  "version": "2.4.2",
+  "version": "3.0.0-dev.20250211",
   "description": "OpenAPI definitions and converters for 'typia' and 'nestia'.",
   "main": "./lib/index.js",
   "module": "./lib/index.mjs",

src/OpenApi.ts

@@ -6,6 +6,7 @@ import { OpenApiV3Upgrader } from "./converters/OpenApiV3Upgrader";
 import { OpenApiV3_1Emender } from "./converters/OpenApiV3_1Emender";
 import { SwaggerV2Downgrader } from "./converters/SwaggerV2Downgrader";
 import { SwaggerV2Upgrader } from "./converters/SwaggerV2Upgrader";
+import { IJsonSchemaAttribute } from "./structures/IJsonSchemaAttribute";
 
 /**
  * Emended OpenAPI v3.1 definition used by `typia` and `nestia`.
@@ -1106,32 +1107,7 @@ export namespace OpenApi {
     /**
      * Common attributes that can be applied to all types.
      */
-    export interface __IAttribute {
-      /**
-       * 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 type __IAttribute = IJsonSchemaAttribute;
   }
 
   /**

src/index.ts

@@ -6,6 +6,7 @@ export * from "./SwaggerV2";
 export * from "./OpenApiV3";
 export * from "./OpenApiV3_1";
 
+export * from "./structures/IJsonSchemaAttribute";
 export * from "./utils/OpenApiTypeChecker";
 
 //----

src/structures/IChatGptSchema.ts

@@ -1,3 +1,5 @@
+import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
+
 /**
  * Type schema info of the ChatGPT.
  *
@@ -279,32 +281,7 @@ export namespace IChatGptSchema {
   /**
    * Common attributes that can be applied to all types.
    */
-  export interface __IAttribute {
-    /**
-     * 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 type __IAttribute = IJsonSchemaAttribute;
 
   /**
    * Configuration for ChatGPT schema composition.

src/structures/IGeminiSchema.ts

@@ -1,3 +1,5 @@
+import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
+
 /**
  * Type schema info for the Gemini function calling.
  *
@@ -226,33 +228,7 @@ export namespace IGeminiSchema {
   /**
    * Common attributes that can be applied to all types.
    */
-  export interface __IAttribute {
-    /**
-     * Detailed description of the schema.
-     */
-    description?: string;
-
-    /**
-     * Whether the type is deprecated or not.
-     *
-     * @warning document of Gemini says not supported, but cannot sure
-     */
-    deprecated?: boolean;
-
-    /**
-     * Example value.
-     *
-     * @warning document of Gemini says not supported, but cannot sure
-     */
-    example?: any;
-
-    /**
-     * List of example values as key-value pairs.
-     *
-     * @warning document of Gemini says not supported, but cannot sure
-     */
-    examples?: Record<string, any>;
-  }
+  export type __IAttribute = IJsonSchemaAttribute;
 
   /**
    * Configuration for the Gemini schema composition.

src/structures/IJsonSchemaAttribute.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 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`.
+ *
+ * ```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;
+ *   }
+ * }
+ * ```
+ *
+ * @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>;
+}

src/structures/ILlmSchemaV3.ts

@@ -1,3 +1,5 @@
+import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
+
 /**
  * Type schema based on OpenAPI v3.0 for LLM function calling.
  *
@@ -435,32 +437,7 @@ export namespace ILlmSchemaV3 {
   /**
    * Common attributes that can be applied to all types.
    */
-  export interface __IAttribute {
-    /**
-     * 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 type __IAttribute = IJsonSchemaAttribute;
 
   /**
    * Configuration for OpenAPI v3.0 based LLM schema composition.

src/structures/ILlmSchemaV3_1.ts

@@ -1,3 +1,5 @@
+import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
+
 /**
  * Type schema based on OpenAPI v3.1 for LLM function calling.
  *
@@ -478,32 +480,7 @@ export namespace ILlmSchemaV3_1 {
   /**
    * Common attributes that can be applied to all types.
    */
-  export interface __IAttribute {
-    /**
-     * 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 type __IAttribute = IJsonSchemaAttribute;
 
   /**
    * Configuration for OpenAPI v3.1 based LLM schema composition.