Lighten up JSON Schema

The JSON schema generated by the `typia.json.application<Types>()` function was quite extensive and lax. The first reason is that when `IJsonSchema.IAttribute` properties are union or array types, they are assigned equally to nested types. And the second reason is the special properties of `typia` that starts with `x-typia-`.

Until now, there was no reason for the JSON Schema generated by `typia` to be lightweight. However, recently, as LLM models with ChatGPT as a topic have become popular, and they have started to use a model that charges by token (word), a problem has arisen. JSON Schema is entered into the ChatGPT (LLM) API and utilized to create various AI-enabled services, but these characteristics of the `typia.json.application<Types>()` function ultimately resulted in excessive token charges.

Accordingly, this PR first prevented `IJsonSchema.IAttribute` from being excessively allocated. Second, a new generic argument `Surplus` was added to the `typia.json.application<Types, Purpose, Surplus>()` function that can determine whether to use additional properties starting with `x-typia-`. Of course, the default value for this is `false`.

```typescript
/**
 * JSON Schema Application.
 *
 * Creates a JSON schema application which contains both main JSON schemas and
 * components. Note that, all of the named types are stored in the
 * {@link IJsonApplication.components} property for the `$ref` referencing.
 *
 * Also, `typia.json.application()` has two additional generic arguments.
 *
 * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
 * For an example, `ajv` has an extra property "$recursiveRef"  that are not
 * exists in the standard JSON schema definition spec. Otherwise, `swagger`
 * can't identify the tuple definition.
 *
 * The next *Surplus* means whether to allow surplus properties starting with
 * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
 * would be registered into the JSON schema, otherwise, not.
 *
 * @template Types Tuple of target types
 * @template Purpose Purpose of the JSON schema
 * @template Surplus Allow surplus properties starting with `x-typia-` or not
 * @return JSON schema application
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function application<
  Types extends unknown[],
  Purpose extends "ajv" | "swagger" = "swagger",
  Surplus extends boolean = false,
>(): IJsonApplication;
```

benchmark/package.json

@@ -73,6 +73,6 @@
     "suppress-warnings": "^1.0.2",
     "tstl": "^2.5.13",
     "uuid": "^9.0.1",
-    "typia": "D:\\github\\samchon\\typia\\typia-5.3.7.tgz"
+    "typia": "D:\\github\\samchon\\typia\\typia-5.3.8-dev.20240103.tgz"
   }
 }

benchmark/src/structures/zod/ZodUltimateUnion.ts

@@ -95,6 +95,7 @@ const Application: z.ZodType<IJsonApplication> = z.lazy(() =>
     components: Components,
     purpose: z.union([z.literal("ajv"), z.literal("swagger")]),
     prefix: z.string(),
+    surplus: z.boolean(),
   }),
 );
 

errors/package.json

@@ -32,6 +32,6 @@
     "typescript": "^5.3.2"
   },
   "dependencies": {
-    "typia": "D:\\github\\samchon\\typia\\typia-5.3.7.tgz"
+    "typia": "D:\\github\\samchon\\typia\\typia-5.3.8-dev.20240103.tgz"
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "typia",
-  "version": "5.3.7",
+  "version": "5.3.8-dev.20240103",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

packages/typescript-json/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-json",
-  "version": "5.3.7",
+  "version": "5.3.8-dev.20240103",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -61,7 +61,7 @@
   },
   "homepage": "https://typia.io",
   "dependencies": {
-    "typia": "5.3.7"
+    "typia": "5.3.8-dev.20240103"
   },
   "peerDependencies": {
     "typescript": ">=4.8.0 <5.4.0"

src/json.ts

@@ -20,19 +20,23 @@ import { Primitive } from "./Primitive";
  * JSON Schema Application.
  *
  * Creates a JSON schema application which contains both main JSON schemas and
- * components. Note that, all of the object types are stored in the
+ * components. Note that, all of the named types are stored in the
  * {@link IJsonApplication.components} property for the `$ref` referencing.
  *
- * Also, `typia.json.application()` has additional generic arguments, *Purpose*.
- * As JSON schema definitions used by `swagger` and `ajv` are different a little bit,
- * you should configure the *Purpose* appropriately.
+ * Also, `typia.json.application()` has two additional generic arguments.
  *
- * For an example, `ajv` has an extra property "$recursiveRef" that are not exists
- * in the standard JSON schema definition spec. Otherwise, `swagger` can't identify
- * the tuple definition.
+ * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
+ * For an example, `ajv` has an extra property "$recursiveRef"  that are not
+ * exists in the standard JSON schema definition spec. Otherwise, `swagger`
+ * can't identify the tuple definition.
+ *
+ * The next *Surplus* means whether to allow surplus properties starting with
+ * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
+ * would be registered into the JSON schema, otherwise, not.
  *
  * @template Types Tuple of target types
- * @template Purpose Purpose of the JSON schema`
+ * @template Purpose Purpose of the JSON schema
+ * @template Surplus Allow surplus properties starting with `x-typia-` or not
  * @return JSON schema application
  *
  * @author Jeongho Nam - https://github.com/samchon
@@ -43,26 +47,31 @@ export function application(): never;
  * JSON Schema Application.
  *
  * Creates a JSON schema application which contains both main JSON schemas and
- * components. Note that, all of the object types are stored in the
+ * components. Note that, all of the named types are stored in the
  * {@link IJsonApplication.components} property for the `$ref` referencing.
  *
- * Also, `typia.json.application()` has additional generic arguments, *Purpose*.
- * As JSON schema definitions used by `swagger` and `ajv` are different a little bit,
- * you should configure the *Purpose* appropriately.
+ * Also, `typia.json.application()` has two additional generic arguments.
+ *
+ * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
+ * For an example, `ajv` has an extra property "$recursiveRef"  that are not
+ * exists in the standard JSON schema definition spec. Otherwise, `swagger`
+ * can't identify the tuple definition.
  *
- * For an example, `ajv` has an extra property "$recursiveRef" that are not exists
- * in the standard JSON schema definition spec. Otherwise, `swagger` can't identify
- * the tuple definition.
+ * The next *Surplus* means whether to allow surplus properties starting with
+ * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
+ * would be registered into the JSON schema, otherwise, not.
  *
  * @template Types Tuple of target types
  * @template Purpose Purpose of the JSON schema
+ * @template Surplus Allow surplus properties starting with `x-typia-` or not
  * @return JSON schema application
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export function application<
   Types extends unknown[],
   Purpose extends "ajv" | "swagger" = "swagger",
+  Surplus extends boolean = false,
 >(): IJsonApplication;
 
 /**

src/programmers/internal/application_array.ts

@@ -12,14 +12,12 @@ import { application_schema } from "./application_schema";
 export const application_array =
   (options: JsonApplicationProgrammer.IOptions) =>
   (components: IJsonComponents) =>
-  (array: MetadataArray) =>
-  (attribute: IJsonSchema.IAttribute): IJsonSchema.IArray[] => {
+  (array: MetadataArray): IJsonSchema.IArray[] => {
     // BASE SCHEMA
     const items: IJsonSchema = application_schema(options)(false)(components)(
       array.type.value,
-    )(attribute);
+    )({});
     const base: IJsonSchema.IArray = {
-      ...attribute,
       type: "array",
       items: null!,
     };
@@ -31,7 +29,7 @@ export const application_array =
 
     // CONSIDER TYPE TAGS
     const union: IJsonSchema.IArray[] = array.tags.map(
-      (row) => application_array_tags({ ...base })(row)!,
+      (row) => application_array_tags(options)({ ...base })(row)!,
     );
     const map: Map<string, IJsonSchema.IArray> = new Map(
       union.map((u) => [JSON.stringify(u), u]),
@@ -40,20 +38,22 @@ export const application_array =
   };
 
 const application_array_tags =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (schema: IJsonSchema.IArray) =>
   (row: IMetadataTypeTag[]): IJsonSchema.IArray => {
     for (const tag of row.slice().sort((a, b) => a.kind.localeCompare(b.kind)))
       if (tag.kind === "minItems" && typeof tag.value === "number")
         schema.minItems = tag.value;
       else if (tag.kind === "maxItems" && typeof tag.value === "number")
         schema.maxItems = tag.value;
-    schema["x-typia-typeTags"] = row.map((tag) => ({
-      target: tag.target,
-      name: tag.name,
-      kind: tag.kind,
-      value: tag.value,
-      validate: tag.validate,
-      exclusive: tag.exclusive,
-    }));
+    if (options.surplus)
+      schema["x-typia-typeTags"] = row.map((tag) => ({
+        target: tag.target,
+        name: tag.name,
+        kind: tag.kind,
+        value: tag.value,
+        validate: tag.validate,
+        exclusive: tag.exclusive,
+      }));
     return schema;
   };

src/programmers/internal/application_boolean.ts

@@ -2,16 +2,17 @@ import { IMetadataTypeTag } from "../../schemas/metadata/IMetadataTypeTag";
 import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
 
 import { IJsonSchema } from "../../module";
+import { JsonApplicationProgrammer } from "../json/JsonApplicationProgrammer";
 import { application_default } from "./application_default";
 
 /**
  * @internal
  */
 export const application_boolean =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (atomic: MetadataAtomic) =>
   (attribute: IJsonSchema.IAttribute): IJsonSchema.IBoolean[] => {
     const base: IJsonSchema.IBoolean = {
-      ...attribute,
       default: application_default(attribute)(
         (alias) => alias === "true" || alias === "false",
       )((str) => Boolean(str)),
@@ -25,6 +26,10 @@ export const application_boolean =
     return defaultTags.map((tag) => ({
       ...base,
       default: tag.value,
-      "x-typia-typeTags": defaultTags,
+      ...(options.surplus
+        ? {
+            "x-typia-typeTags": defaultTags,
+          }
+        : {}),
     }));
   };

src/programmers/internal/application_constant.ts

@@ -9,7 +9,6 @@ import { application_default } from "./application_default";
 export const application_constant =
   (constant: MetadataConstant) =>
   (attribute: IJsonSchema.IAttribute): IJsonSchema.IEnumeration<any> => ({
-    ...attribute,
     type: constant.type,
     enum: constant.values as any,
     default: application_default(attribute)((alias) =>

src/programmers/internal/application_escaped.ts

@@ -9,11 +9,10 @@ export const application_escaped =
   (options: JsonApplicationProgrammer.IOptions) =>
   <BlockNever extends boolean>(blockNever: BlockNever) =>
   (components: IJsonComponents) =>
-  (resolved: MetadataEscaped) =>
-  (attribute: IJsonSchema.IAttribute): IJsonSchema[] => {
+  (resolved: MetadataEscaped): IJsonSchema[] => {
     const output = application_schema(options)(blockNever)(components)(
       resolved.returns,
-    )(attribute);
+    )({});
     if (output === null) return [];
 
     if (is_date(new Set())(resolved.original)) {

src/programmers/internal/application_native.ts

@@ -11,14 +11,11 @@ export const application_native =
   (options: JsonApplicationProgrammer.IOptions) =>
   (components: IJsonComponents) =>
   (name: string) =>
-  (props: {
-    nullable: boolean;
-    attribute: IJsonSchema.IAttribute;
-  }): IJsonSchema.IReference => {
+  (nullable: boolean): IJsonSchema.IReference => {
     const key: string =
       options.purpose === "ajv"
         ? name
-        : `${name}${props.nullable ? ".Nullable" : ""}`;
+        : `${name}${nullable ? ".Nullable" : ""}`;
     if (components.schemas?.[key] === undefined) {
       components.schemas ??= {};
       components.schemas[key] ??= {
@@ -28,11 +25,10 @@ export const application_native =
             ? `${JSON_COMPONENTS_PREFIX}/objects/${key}`
             : undefined,
         properties: {},
-        nullable: options.purpose === "swagger" ? props.nullable : undefined,
+        nullable: options.purpose === "swagger" ? nullable : undefined,
       };
     }
     return {
-      ...props.attribute,
       $ref: `${JSON_COMPONENTS_PREFIX}/objects/${key}`,
     };
   };

src/programmers/internal/application_number.ts

@@ -2,6 +2,7 @@ import { IMetadataTypeTag } from "../../schemas/metadata/IMetadataTypeTag";
 import { MetadataAtomic } from "../../schemas/metadata/MetadataAtomic";
 
 import { IJsonSchema } from "../../module";
+import { JsonApplicationProgrammer } from "../json/JsonApplicationProgrammer";
 import { application_default } from "./application_default";
 
 type Schema = IJsonSchema.INumber | IJsonSchema.IInteger;
@@ -10,11 +11,11 @@ type Schema = IJsonSchema.INumber | IJsonSchema.IInteger;
  * @internal
  */
 export const application_number =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (atomic: MetadataAtomic) =>
   (attribute: IJsonSchema.IAttribute): Array<Schema> => {
     // BASE CONFIGURATION
     const base: Schema = {
-      ...attribute,
       type: "number",
     };
     const out = (schema: Schema) => {
@@ -39,7 +40,7 @@ export const application_number =
 
     // CONSIDER TYPE TAGS
     const union: Schema[] = atomic.tags.map(
-      (row) => application_number_tags({ ...base })(row)!,
+      (row) => application_number_tags(options)({ ...base })(row)!,
     );
     const map: Map<string, Schema> = new Map(
       union.map((u) => [JSON.stringify(u), u]),
@@ -48,6 +49,7 @@ export const application_number =
   };
 
 const application_number_tags =
+  (options: JsonApplicationProgrammer.IOptions) =>
   (base: Schema) =>
   (row: IMetadataTypeTag[]): Schema => {
     for (const tag of row
@@ -82,13 +84,14 @@ const application_number_tags =
       else if (tag.kind === "default" && typeof tag.value === "number")
         base.default = tag.value;
     }
-    base["x-typia-typeTags"] = row.map((tag) => ({
-      target: tag.target,
-      name: tag.name,
-      kind: tag.kind,
-      value: tag.value,
-      validate: tag.validate,
-      exclusive: tag.exclusive,
-    }));
+    if (options.surplus)
+      base["x-typia-typeTags"] = row.map((tag) => ({
+        target: tag.target,
+        name: tag.name,
+        kind: tag.kind,
+        value: tag.value,
+        validate: tag.validate,
+        exclusive: tag.exclusive,
+      }));
     return base;
   };

src/programmers/internal/application_object.ts

@@ -84,11 +84,15 @@ const create_object_schema =
             : undefined;
         })(),
         description: property.description ?? undefined,
-        "x-typia-jsDocTags": property.jsDocTags.length
-          ? property.jsDocTags
-          : undefined,
-        "x-typia-required": property.value.required,
-        "x-typia-optional": property.value.optional,
+        ...(options.surplus
+          ? {
+              "x-typia-jsDocTags": property.jsDocTags.length
+                ? property.jsDocTags
+                : undefined,
+              "x-typia-required": property.value.required,
+              "x-typia-optional": property.value.optional,
+            }
+          : {}),
       });
 
       if (schema === null) continue;
@@ -125,12 +129,14 @@ const create_object_schema =
       "x-typia-jsDocTags": obj.jsDocTags,
       ...(options.purpose === "ajv"
         ? extraProps
-        : {
+        : options.surplus
+        ? {
             // swagger can't express patternProperties
             "x-typia-additionalProperties": extraProps.additionalProperties,
             "x-typia-patternProperties": extraProps.patternProperties,
             additionalProperties: join(options)(components)(extraMeta),
-          }),
+          }
+        : {}),
     };
   };
 
@@ -153,9 +159,13 @@ const join =
       .map((tuple) => tuple[0])
       .reduce((x, y) => Metadata.merge(x, y));
     return (
-      application_schema(options)(true)(components)(meta)({
-        "x-typia-required": false,
-      }) ?? undefined
+      application_schema(options)(true)(components)(meta)(
+        options.surplus
+          ? {
+              "x-typia-required": false,
+            }
+          : {},
+      ) ?? undefined
     );
   };