refactor(types): replace json-schema library with custom JSONSchema type (#220)

* refactor(types): replace json-schema library with custom JSONSchema type

- Define comprehensive JSONSchema interface in types.ts covering all
  JSON Schema draft-07 properties
- Add toJsonSchema() method to BaseTool and Tools classes for
  framework-agnostic schema export
- Refactor toOpenAI(), toAnthropic(), and toOpenAIResponses() to use
  toJsonSchema() internally, reducing code duplication
- Use type-fest OverrideProperties for ObjectJSONSchema type to ensure
  type: 'object' is always set
- Remove json-schema and @types/json-schema dependencies

This reduces external dependencies while providing a more flexible
JSONSchema type that works seamlessly with OpenAI, Anthropic, and
other LLM providers.

* refactor(tool): use toJsonSchema() in toAISDK method

Consolidate schema generation by reusing toJsonSchema() instead of
manually constructing the schema object. This reduces duplication
and ensures consistency across all conversion methods.

* refactor(tool): add type-safe schema validation for AI SDK

- Import JSONSchema7 type from @ai-sdk/provider as AISDKJSONSchema
- Use satisfies AISDKJSONSchema to validate schema at compile time
- Move jsonSchema type import to top-level for cleaner code
- Add @ai-sdk/provider as dev dependency for type checking

* refactor(utils): add tryImport utility for optional dependencies

- Create tryImport() helper function for dynamic imports with friendly
  error messages when optional dependencies are not installed
- Refactor toAISDK() to use tryImport() for cleaner code
- Remove unused jsonSchema type import from top-level

* test(utils): add tests for tryImport utility

- Test successful import of existing modules
- Test StackOneError is thrown for non-existent modules
- Verify error message includes module name and install hint

* refactor(tool): clean up toAISDK method

- Remove deprecated v4 parameters property
- Use satisfies for type-safe tool definition
- Remove outdated TODO comment about ts-ignore
- Simplify tool definition by constructing all properties upfront

* chore(oxfmt): ignore .claude/settings.local.json

* chore(deps): move @ai-sdk/provider to catalog:dev

* docs: tanstack ai jsonschema

* Revert "chore(oxfmt): ignore .claude/settings.local.json"

This reverts commit 91d6c79.

Author: ryoppippi

package.json

@@ -38,13 +38,12 @@
 		"@modelcontextprotocol/sdk": "catalog:prod",
 		"@orama/orama": "catalog:prod",
 		"defu": "catalog:prod",
-		"json-schema": "catalog:prod",
 		"zod": "catalog:dev"
 	},
 	"devDependencies": {
+		"@ai-sdk/provider": "catalog:dev",
 		"@ai-sdk/provider-utils": "catalog:dev",
 		"@hono/mcp": "catalog:dev",
-		"@types/json-schema": "catalog:dev",
 		"@types/node": "catalog:dev",
 		"@typescript/native-preview": "catalog:dev",
 		"@vitest/coverage-v8": "catalog:dev",

pnpm-lock.yaml

@@ -7,10 +7,10 @@ catalogMode: strict
 catalogs:
   dev:
     '@ai-sdk/openai': ^2.0.80
-    '@clack/prompts': ^0.11.0
+    '@ai-sdk/provider': ^2.0.0
     '@ai-sdk/provider-utils': ^3.0.18
+    '@clack/prompts': ^0.11.0
     '@hono/mcp': ^0.1.4
-    '@types/json-schema': ^7.0.15
     '@types/node': ^22.13.5
     '@typescript/native-preview': ^7.0.0-dev.20251209.1
     '@vitest/coverage-v8': ^4.0.15
@@ -35,7 +35,6 @@ catalogs:
     '@modelcontextprotocol/sdk': ^1.24.3
     '@orama/orama': ^3.1.11
     defu: ^6.1.4
-    json-schema: ^0.4.0
 
 enablePrePostScripts: true
 

pnpm-workspace.yaml

@@ -1,7 +1,11 @@
 import { jsonSchema } from 'ai';
-import type { JSONSchema7 } from 'json-schema';
 import { BaseTool, type MetaToolSearchResult, StackOneTool, Tools } from './tool';
-import { type ExecuteConfig, ParameterLocation, type ToolParameters } from './types';
+import {
+	type ExecuteConfig,
+	type JSONSchema,
+	ParameterLocation,
+	type ToolParameters,
+} from './types';
 import { StackOneAPIError } from './utils/errors';
 
 // Create a mock tool for testing
@@ -1107,11 +1111,10 @@ describe('Schema Validation', () => {
 			);
 
 			const parameters = tool.toOpenAI().function.parameters;
-			expect(parameters).toBeDefined();
-			const properties = parameters?.properties as Record<string, JSONSchema7>;
+			const properties = parameters?.properties as Record<string, JSONSchema>;
 
 			expect(properties.arrayWithItems.items).toBeDefined();
-			expect((properties.arrayWithItems.items as JSONSchema7).type).toBe('number');
+			expect((properties.arrayWithItems.items as JSONSchema).type).toBe('number');
 		});
 
 		it('should handle nested object structure', () => {
@@ -1144,7 +1147,7 @@ describe('Schema Validation', () => {
 
 			const parameters = tool.toOpenAI().function.parameters;
 			expect(parameters).toBeDefined();
-			const properties = parameters?.properties as Record<string, JSONSchema7>;
+			const properties = parameters?.properties as Record<string, JSONSchema>;
 			const nestedObject = properties.nestedObject;
 
 			expect(nestedObject.type).toBe('object');
@@ -1185,7 +1188,7 @@ describe('Schema Validation', () => {
 			// @ts-ignore - jsonSchema is available on Schema wrapper from ai sdk
 			const arrayWithItems = toolObj.inputSchema.jsonSchema.properties?.arrayWithItems;
 			expect(arrayWithItems?.type).toBe('array');
-			expect((arrayWithItems?.items as JSONSchema7)?.type).toBe('string');
+			expect((arrayWithItems?.items as JSONSchema)?.type).toBe('string');
 		});
 
 		it('should handle nested filter object for AI SDK', async () => {
@@ -1220,14 +1223,14 @@ describe('Schema Validation', () => {
 
 			const parameters = tool.toOpenAI().function.parameters;
 			expect(parameters).toBeDefined();
-			const aiSchema = jsonSchema(parameters as JSONSchema7);
+			const aiSchema = jsonSchema(parameters as JSONSchema);
 			expect(aiSchema).toBeDefined();
 
 			const aiSdkTool = await tool.toAISDK();
 			// TODO: Remove ts-ignore once AISDKToolDefinition properly types inputSchema.jsonSchema
 			// @ts-ignore - jsonSchema is available on Schema wrapper from ai sdk
 			const filterProp = aiSdkTool[tool.name].inputSchema.jsonSchema.properties?.filter as
-				| (JSONSchema7 & { properties: Record<string, JSONSchema7> })
+				| (JSONSchema & { properties: Record<string, JSONSchema> })
 				| undefined;
 
 			expect(filterProp?.type).toBe('object');