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

Make @wrtnlabs/schema concisely. #18

Merged
merged 5 commits into from
Mar 4, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
@@ -1,18 +1,11 @@
name: build
on:
push:
paths:
- 'examples/**'
- 'src/**'
- 'test/**'
- 'package.json'
on:
pull_request:
paths:
- 'examples/**'
- 'src/**'
- 'test/**'
- 'package.json'

jobs:
Ubuntu:
runs-on: ubuntu-latest
Expand All @@ -21,10 +14,12 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: 20.x

- uses: pnpm/action-setup@v2
with:
version: 8
- name: Install dependencies
run: npm install
run: pnpm install
- name: Build
run: npm run build
run: pnpm run build
- name: Test
run: npm run test
run: pnpm run test
30 changes: 30 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# author: elliot-huffman
name: release
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: none
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20.x
registry-url: https://registry.npmjs.org/
- uses: pnpm/action-setup@v2
with:
version: 8
- name: Install dependencies
run: pnpm install
- name: Build
run: pnpm run build
- name: Test
run: pnpm run test
- name: Publish to npm
run: npm publish --provenance
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH }}
14 changes: 14 additions & 0 deletions .github/workflows/spell-check.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
name: spell-check
on:
pull_request:

jobs:
spell-check:
runs-on: ubuntu-latest
steps:
- name: Checkout Actions Repository
uses: actions/checkout@v4

- uses: crate-ci/typos@master
with:
config: ./typos.toml
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,4 @@ lib/
node_modules/

package-lock.json
pnpm-lock.yaml
*.log
146 changes: 14 additions & 132 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,139 +1,21 @@
# `@wrtnio/schema`
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wrtnio/schema/blob/master/LICENSE)
[![npm version](https://img.shields.io/npm/v/@wrtnio/schema.svg)](https://www.npmjs.com/package/@wrtnio/schema)
[![Downloads](https://img.shields.io/npm/dm/@wrtnio/schema.svg)](https://www.npmjs.com/package/@wrtnio/schema)
[![Build Status](https://github.com/wrtnio/schema/workflows/build/badge.svg)](https://github.com/wrtnio/schema/actions?query=workflow%3Abuild)
# `@wrtnlabs/schema`
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wrtnlabs/schema/blob/master/LICENSE)
[![npm version](https://img.shields.io/npm/v/@wrtnlabs/schema.svg)](https://www.npmjs.com/package/@wrtnlabs/schema)
[![Downloads](https://img.shields.io/npm/dm/@wrtnlabs/schema.svg)](https://www.npmjs.com/package/@wrtnlabs/schema)
[![Build Status](https://github.com/wrtnlabs/schema/workflows/build/badge.svg)](https://github.com/wrtnlabs/schema/actions?query=workflow%3Abuild)

Extension of [`@samchon/openapi`](https://github.com/samchon/openapi) adding plugin properties.

`@wrtnio/schema` is a collection of Swagger (OpenAPI) and OpenAI (LLM, Large Language Model) function calling schemas that is extended from `@samchon/openapi` library adding some plugin properties like `x-wrtn-secret-key`, especially for the Wrtn Studio Pro.

- Wrtn Studio Pro Application: https://studio-pro.wrtn.ai
- Wrtn Studio Pro Documents: https://wrtn.ai/studio-pro/

Here is the list of extended types from the `@samchon/openapi`, and you can use these `@wrtnio/schema` types just by combining with the `@samchon/openapi` provided functions like below. Note that, every types defined in the `@wrtnio/schema` are compatible with `@samchon/openapi`.
You can see the plugin properties in the [`src/index.ts`](https://github.com/wrtnlabs/schema/blob/main/src/index.ts) file.

```typescript
import { HttpLlm, OpenApi } from "@samchon/openapi";
import { IHttpOpenAiApplication, ISwagger } from "@wrtnio/schema";

const document: ISwagger = OpenApi.convert(YOUR_SWAGGER_DOCUMENT);
const application: IHttpOpenAiApplication = HttpLlm.application(document);
import { OpenApi.IJsonSchema } from "@samchon/openapi";
import "@wrtnlabs/schema";

const schema: OpenApi.IJsonSchema = {
type: "string",
format: "email",
"x-wrtn-placeholder": "Insert your email address please",
};
```

Kind | `@wrtnio/schema` | `@samchon/openapi`
-------------------------------------------------------------------------------------------|------------------------------|---------------------------
[**HTTP LLM Application**](https://wrtn.ai/studio-pro/tech-specs/meta/schema/#application) | **`IHttpOpenAiApplication`** | **`IHttpLlmApplication<"3.0">`**
[HTTP LLM Function Schema](https://wrtn.ai/studio-pro/tech-specs/meta/schema/#function) | `IHttpOpenAiFunction` | `IHttpLlmFunction<3.0">`
[LLM Type Schema](https://wrtn.ai/studio-pro/tech-specs/meta/schema/#schema) | `IOpenAiSchema` | `ILlmSchema<"3.0">`
[**OpenAPI Document**](https://wrtn.ai/studio-pro/tech-specs/openapi/document/#document) | **`ISwagger`** | **`OpenApi.IDocument`**
[Server URL Address](https://wrtn.ai/studio-pro/tech-specs/openapi/document/#server) | `ISwaggerServer` | `OpenApi.IServer`
[API Operation](https://wrtn.ai/studio-pro/tech-specs/openapi/document/#operation) | `ISwaggerOperation` | `OpenApi.IOperation`
[JSON Schema](https://wrtn.ai/studio-pro/tech-specs/openapi/json/) | `ISwaggerSchema` | `OpenApi.IJsonSchema`
[Security Scheme](https://wrtn.ai/studio-pro/tech-specs/openapi/document/#security-scheme) | `ISwaggerSecuritySchema` | `OpenApi.ISecurityScheme`
[Schema Components](https://wrtn.ai/studio-pro/tech-specs/openapi/json/#components) | `ISwaggerComponents` | `OpenApi.IComponents`




## Plugin Properties
Plugin properties starting with `x-wrtn-` in type schemas.

Only the difference between `@wrtnio/schema` and `@samchon/openapi` is, `@wrtnio/schema` is filling JSON and LLM function calling type schemas with plugin properties which are starting from the `x-wrtn-` prefix key name.

At first, `x-wrtn-placeholder` and `x-wrtn-prerequisite` properties are defined in the every type schemas. The `x-wrtn-placeholder` means the placeholder text in the UI input component as literally, and `x-wrtn-prerequisite` directs the pre-requisite API operation endpoint to compose the target value with JMesPath expression.

- every types in the `ISwaggerSchema`
- every types in the `IOpenAiSchema`

```typescript
// adjusted to every JSON and LLM type schemas
export interface ISwaggerSchemaPlugin {
/**
* Placeholder value for frontend application.
*
* Placeholder means the value to be shown in the input field as a hint.
* For example, when an email input field exists, the placeholder value
* would be "Insert your email address here".
*/
"x-wrtn-placeholder"?: string;

/**
* Prerequisite API endpoint for the schema.
*
* `x-wrtn-prerequisite` is a property representing the prerequisite API
* interaction. It means that, the endpoint API should be called before
* calling the target API, for composing some argument value.
*
* @reference https://github.com/wrtnio/decorators/blob/main/src/Prerequisite.ts
*/
"x-wrtn-prerequisite"?: ISwaggerSchemaPlugin.IPrerequisite;
}
export namespace ISwaggerSchemaPlugin {
export interface IPrerequisite {
/**
* HTTP method to call the endpoint.
*/
method: "get" | "post" | "patch" | "put" | "delete";

/**
* Path of the endpoint.
*/
path: string;

/**
* Function returning transformed values using JMESPath expression.
*
* `Prerequisite.Props.jmesPath` is a string typed property that extracts desired values
* from the prerequisite API response using a JMESPath expression. This property simplifies
* and replaces the `label`, `value`, and `array` properties.
*
* JMESPath expressions are used to extract the desired data based on the API response.
* The expression must always be a valid JMESPath syntax.
*
* - Type: `jmesPath: string`
* - Example: `"members[*].data.title"`
* - Usage: `jmespath.search(response, jmesPath)`
*
* Note: The `label`, `value`, and `array` properties are no longer in use.
*/
jmesPath: string;
}
}
```

Also, the `string` typed schema has two additional properties about secret identification.

- `ISwaggerSchema.IString`
- `IOpenAiSchema.IString`

The first property `x-wrtn-secret-key` means secret key of a specific service, and the second property `x-wrtn-secret-scopes` means a list of secret scopes that are required for the target API endpoint calling.

```typescript
export namespace ISwaggerSchema {
/**
* String type info.
*/
export interface IString
extends OpenApi.IJsonSchema.IString,
ISwaggerSchemaPlugin {
/**
* 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;

/**
* Secret scopes for the schema.
*
* `x-wrtn-secret-scopes` is a property means a list of secret scopes that
* are required for the target API endpoint calling. If the secret scopes
* are not satisfied, the API call would be failed.
*/
"x-wrtn-secret-scopes"?: string[];
}
}
```
28 changes: 11 additions & 17 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@wrtnio/schema",
"version": "3.2.1",
"name": "@wrtnlabs/schema",
"version": "4.0.0",
"description": "JSON and LLM function calling schemas extended for Wrtn Studio Pro",
"main": "lib/index.js",
"module": "./lib/index.mjs",
Expand All @@ -20,41 +20,35 @@
"keywords": [
"swagger",
"openapi",
"llm-function-call",
"openai",
"wrtn"
"json-schema",
"llm-function-calling-schema",
"plugin"
],
"author": "Jeongho Nam",
"author": "Samchon",
"license": "MIT",
"bugs": {
"url": "https://github.com/wrtnio/schema/issues"
},
"homepage": "https://github.com/wrtnio/schema#readme",
"dependencies": {
"@samchon/openapi": "^2.3.3"
"@samchon/openapi": "^3.0.0"
},
"devDependencies": {
"@nestia/core": "^4.4.2",
"@nestia/e2e": "^0.7.0",
"@nestia/fetcher": "^4.4.2",
"@nestia/sdk": "^4.4.2",
"@nestjs/common": "^10.4.12",
"@nestjs/core": "^10.4.12",
"@nestjs/platform-express": "^10.4.12",
"@nestia/e2e": "^0.8.2",
"@rollup/plugin-terser": "^0.4.4",
"@rollup/plugin-typescript": "^11.1.6",
"@trivago/prettier-plugin-sort-imports": "^4.3.0",
"@types/multer": "^1.4.12",
"@types/node": "^22.13.9",
"chalk": "4.1.2",
"multer": "^1.4.5-lts.1",
"prettier": "^3.3.3",
"rimraf": "^6.0.1",
"rollup": "^4.22.0",
"source-map-support": "^0.5.21",
"ts-patch": "^3.2.1",
"typescript": "~5.7.2",
"typescript": "~5.8.2",
"typescript-transform-paths": "^3.5.2",
"typia": "^7.4.1"
"typia": "^8.0.0"
},
"files": [
"lib",
Expand Down
Loading