Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Lighten up JSON Schema #916

Merged
merged 2 commits into from
Jan 3, 2024
Merged

Lighten up JSON Schema #916

merged 2 commits into from
Jan 3, 2024

Conversation

samchon
Copy link
Owner

@samchon samchon commented Jan 3, 2024

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.

/**
 * 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;

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;
```
@samchon samchon added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 3, 2024
@samchon samchon self-assigned this Jan 3, 2024
Copy link
Owner Author

@samchon samchon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Succeeded to pass every test programs.

@samchon samchon merged commit d22d2ca into master Jan 3, 2024
3 checks passed
@samchon samchon deleted the features/json branch January 3, 2024 15:51
samchon added a commit that referenced this pull request Jan 9, 2024
When dieting JSON Schema (#916), have taken a mistake that even dieting the `IJsonSchema.default` value when the default value has configured by comment tag (no problem when type tag).

This PR fixes the bug, so that revived the comment tag defined default value.
samchon added a commit to samchon/nestia that referenced this pull request Jan 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant