Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/StefanTerdell/json-schema-to-zod
https://github.com/StefanTerdell/json-schema-to-zod
Last synced: 15 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/StefanTerdell/json-schema-to-zod
- Owner: StefanTerdell
- License: isc
- Created: 2021-08-15T19:09:20.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-09-05T18:59:26.000Z (2 months ago)
- Last Synced: 2024-10-18T11:37:33.956Z (24 days ago)
- Language: TypeScript
- Size: 355 KB
- Stars: 328
- Watchers: 3
- Forks: 47
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-zod - `json-schema-to-zod` - Convert your JSON Schemas into Zod schemas. (Convertors and Generators)
README
# Json-Schema-to-Zod
[](https://npmjs.org/package/json-schema-to-zod)
[](https://npmjs.org/package/json-schema-to-zod)
_Looking for the exact opposite? Check out [zod-to-json-schema](https://npmjs.org/package/zod-to-json-schema)_
## Summary
A runtime package and CLI tool to convert JSON schema (draft 4+) objects or files into Zod schemas in the form of JavaScript code.
Before v2 it used [`prettier`](https://www.npmjs.com/package/prettier) for formatting and [`json-refs`](https://www.npmjs.com/package/json-refs) to resolve schemas. To replicate the previous behaviour, please use their respective CLI tools.
Since v2 the CLI supports piped JSON.
## Usage
### Online
[Just paste your JSON schemas here!](https://stefanterdell.github.io/json-schema-to-zod-react/)
### CLI
#### Simplest example
```console
npm i -g json-schema-to-zod
```
```console
json-schema-to-zod -i mySchema.json -o mySchema.ts
```
#### Example with `$refs` resolved and output formatted
```console
npm i -g json-schema-to-zod json-refs prettier
```
```console
json-refs resolve mySchema.json | json-schema-to-zod | prettier --parser typescript > mySchema.ts
```
#### Options
| Flag | Shorthand | Function |
| ------------ | --------- | ---------------------------------------------------------------------------------------------- |
| `--input` | `-i` | JSON or a source file path. Required if no data is piped. |
| `--output` | `-o` | A file path to write to. If not supplied stdout will be used. |
| `--name` | `-n` | The name of the schema in the output |
| `--depth` | `-d` | Maximum depth of recursion in schema before falling back to `z.any()`. Defaults to 0. |
| `--module` | `-m` | Module syntax; `esm`, `cjs` or none. Defaults to `esm` in the CLI and `none` programmaticly. |
| `--type` | `-t` | Export a named type along with the schema. Requires `name` to be set and `module` to be `esm`. |
| `--noImport` | `-ni` | Removes the `import { z } from 'zod';` or equivalent from the output. |
### Programmatic
#### Simple example
```typescript
import { jsonSchemaToZod } from "json-schema-to-zod";
const myObject = {
type: "object",
properties: {
hello: {
type: "string",
},
},
};
const module = jsonSchemaToZod(myObject, { module: "esm" });
// `type` can be either a string or - outside of the CLI - a boolean. If its `true`, the name of the type will be the name of the schema with a capitalized first letter.
const moduleWithType = jsonSchemaToZod(myObject, { name: "mySchema", module: "esm", type: true });
const cjs = jsonSchemaToZod(myObject, { module: "cjs", name: "mySchema" });
const justTheSchema = jsonSchemaToZod(myObject);
```
##### `module`
```typescript
import { z } from "zod";
export default z.object({ hello: z.string().optional() });
```
##### `moduleWithType`
```typescript
import { z } from "zod";
export const mySchema = z.object({ hello: z.string().optional() });
export type MySchema = z.infer;
```
##### `cjs`
```typescript
const { z } = require("zod");
module.exports = { mySchema: z.object({ hello: z.string().optional() }) };
```
##### `justTheSchema`
```typescript
z.object({ hello: z.string().optional() });
```
#### Example with `$refs` resolved and output formatted
```typescript
import { z } from "zod";
import { resolveRefs } from "json-refs";
import { format } from "prettier";
import jsonSchemaToZod from "json-schema-to-zod";
async function example(jsonSchema: Record): Promise{
const { resolved } = await resolveRefs(jsonSchema);
const code = jsonSchemaToZod(resolved);
const formatted = await format(code, { parser: "typescript" });
return formatted;
}
```
#### Overriding a parser
You can pass a function to the `overrideParser` option, which represents a function that receives the current schema node and the reference object, and should return a string when it wants to replace a default output. If the default output should be used for the node just return void.
#### Use at Runtime
The output of this package is not meant to be used at runtime. JSON Schema and Zod does not overlap 100% and the scope of the parsers are purposefully limited in order to help the author avoid a permanent state of chaotic insanity. As this may cause some details of the original schema to be lost in translation, it is instead recommended to use tools such as [Ajv](https://ajv.js.org/) to validate your runtime values directly against the original JSON Schema.
That said, it's possible in most cases to use `eval`. Here's an example that you shouldn't use:
```typescript
const zodSchema = eval(jsonSchemaToZod({ type: "string" }, { module: "cjs" }));
zodSchema.safeParse("Please just use Ajv instead");
```