@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
md 62 lines 3.12 KB
Rendered Raw
1 # Json-Schema-to-Zod
2
3 A package to convert JSON schema (draft 4+) objects into Zod schemas in the form of Zod objects at runtime.
4
5 ## Installation
6
7 ```sh
8 npm install @composio/json-schema-to-zod
9 ```
10
11 ### Simple example
12
13 ```typescript
14 import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
15
16 const jsonSchema = {
17 type: 'object',
18 properties: {
19 hello: {
20 type: 'string',
21 },
22 },
23 };
24
25 const zodSchema = jsonSchemaToZod(jsonSchema);
26 ```
27
28 The root entry builds Zod v3 schemas (`zod/v3`), which every supported zod release ships.
29
30 ### Object-level keywords and `jsonSchemaToZodShape`
31
32 `jsonSchemaToZodShape` converts each entry of `properties` on its own, so assertions that apply to the object as a whole have no place in the shape and are not enforced: `minProperties`, `maxProperties`, `propertyNames`, `uniqueItems`, or a `required` key with no declared property. Keywords on a property (`{ uniqueItems: true, type: 'array' }` as a property schema) are still enforced. When the object-level assertions must hold, use `jsonSchemaToZod`, or check them yourself on the `z.object(shape)` you build.
33
34 ### Zod v4 schemas
35
36 The `/v4` entry builds classic Zod v4 schemas (`zod/v4`) with the same function names, so a caller switches by changing the import path:
37
38 ```typescript
39 import { jsonSchemaToZod, jsonSchemaToZodShape } from '@composio/json-schema-to-zod/v4';
40
41 const zodSchema = jsonSchemaToZod(jsonSchema);
42 const shape = jsonSchemaToZodShape(jsonSchema);
43 ```
44
45 Both builders accept and reject the same values. Beyond that, the v4 builder forwards the JSON Schema annotations a serializer cannot derive from the schema's checks, so `z.toJSONSchema()` and the frameworks built on it see them again:
46
47 - `format`, verbatim, including values such as `binary`, `int64`, and `time`;
48 - `contentEncoding` and `contentMediaType`, verbatim;
49 - `type: "integer"`, since the integer check is a refinement that accepts every integral number, as the root builder and JSON Schema do;
50 - the description, title, and examples text the root builder also writes.
51
52 Pass `{ withoutAnnotations: true }` to leave the annotations out; `{ withoutDescribes: true }` leaves out the description, as it does for the root entry.
53
54 `/v4` requires zod `>= 4.1.13`: importing it under an older release throws at load time. 4.1.13 is the first release whose `zod/v4` shares its metadata registry across copies through `globalThis`. That check covers only the zod copy that builds the schema. If the code that serializes the schema loads its own copy of zod below 4.1.13 (a framework that depends on zod directly rather than as a peer), that copy reads a separate registry and the descriptions and annotations are lost. Keep every zod copy in the process at 4.1.13 or later.
55
56 ### Overriding a parser
57
58 You can pass a function to the `parserOverride` option, which represents a function that receives the current schema node and the reference object, and should return a zod object when it wants to replace a default output. If the default output should be used for the node just return undefined.
59
60 ## Acknowledgements
61
62 This is a fork of [`json-schema-to-zod`](https://github.com/StefanTerdell/json-schema-to-zod).