@cleverbrush/schema-json

Bidirectional JSON Schema (Draft 7 / 2020-12) interop for @cleverbrush/schema.

Import a JSON Schema and get a fully-typed @cleverbrush/schema builder that preserves every constraint. Or convert a builder back to a JSON Schema object for use in OpenAPI specs, form generators, or any other JSON Schema consumer.

When to use this library

• Consuming external APIs — you have a JSON Schema from an OpenAPI spec or a third-party service and want to validate incoming data with full TypeScript type inference.
• OpenAPI / JSON Schema round-trip — generate JSON Schemas from your @cleverbrush/schema validators to embed in API specs.
• Migrating from raw JSON Schema — convert an existing schema catalogue to @cleverbrush/schema builders incrementally.
• Code generation — introspect a JSON Schema at the type level via JsonSchemaNodeToBuilder<S> without running any code.

Installation

npm install @cleverbrush/schema-json
Copy

Peer dependency: @cleverbrush/schema@^2.0.0 must already be installed.

Quick Start

import { fromJsonSchema, toJsonSchema } from '@cleverbrush/schema-json';
import { object, string, number } from '@cleverbrush/schema';

// ── JSON Schema → builder ──────────────────────────────────────────────────
const PersonSchema = fromJsonSchema({
    type: 'object',
    properties: {
        name:  { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        age:   { type: 'integer', minimum: 0 },
    },
    required: ['name', 'email'],
} as const); // ← `as const` is required for precise type inference

const result = PersonSchema.parse({ name: 'Alice', email: 'alice@example.com', age: 30 });
// result.object is typed as { name: string; email: string; age?: number }

// ── Builder → JSON Schema ──────────────────────────────────────────────────
const ApiSchema = object({
    id:    string().uuid(),
    title: string().minLength(1).maxLength(255),
    score: number().min(0).max(100).optional(),
});

const spec = toJsonSchema(ApiSchema);
// {
//   "$schema": "https://json-schema.org/draft/2020-12/schema",
//   "type": "object",
//   "properties": {
//     "id":    { "type": "string", "format": "uuid" },
//     "title": { "type": "string", "minLength": 1, "maxLength": 255 },
//     "score": { "type": "number" }
//   },
//   "required": ["id", "title"]
// }
Copy

API Reference

fromJsonSchema(schema)

Converts a JSON Schema literal to a @cleverbrush/schema builder.

function fromJsonSchema<const S>(schema: S): JsonSchemaNodeToBuilder<S>
Copy

Returns a @cleverbrush/schema builder (e.g. StringSchemaBuilder, ObjectSchemaBuilder, UnionSchemaBuilder, etc.) whose static type mirrors the JSON Schema structure.

as const is required

Without as const, TypeScript widens string literals to string and object shapes to Record<string, unknown>, so inference collapses to SchemaBuilder<unknown>. Always annotate:

const S = { type: 'object', properties: { x: { type: 'number' } } } as const;
const schema = fromJsonSchema(S); // ObjectSchemaBuilder<{ x: NumberSchemaBuilder<...> }>
Copy

Supported JSON Schema keywords

toJsonSchema(schema, opts?)

Converts a @cleverbrush/schema builder to a JSON Schema object.

function toJsonSchema(
    schema: SchemaBuilder<any, any, any>,
    opts?: ToJsonSchemaOptions,
): Record<string, unknown>
Copy

Returns a plain JavaScript object that is safe to JSON.stringify.

Descriptions set via .describe(text) are emitted as the description field on the corresponding JSON Schema node (including nested object properties).

ToJsonSchemaOptions

// Embed in OpenAPI (suppress the $schema header)
toJsonSchema(schema, { $schema: false });

// Use Draft 07
toJsonSchema(schema, { draft: '07' });
Copy

Type Utilities

InferFromJsonSchema<S>

Recursively derives the TypeScript value type from a statically-known JSON Schema. Useful when you want the type without calling fromJsonSchema at runtime.

import type { InferFromJsonSchema } from '@cleverbrush/schema-json';

const S = {
    type: 'object',
    properties: {
        id:    { type: 'integer' },
        label: { type: 'string' },
    },
    required: ['id'],
} as const;

type Item = InferFromJsonSchema<typeof S>;
// { id: number; label?: string }
Copy

JsonSchemaNodeToBuilder<S, TRequired?>

Maps a statically-known JSON Schema literal to the @cleverbrush/schema builder type — purely at the type level, no runtime code executed.

import type { JsonSchemaNodeToBuilder } from '@cleverbrush/schema-json';

const S = { type: 'string', format: 'email' } as const;
type B = JsonSchemaNodeToBuilder<typeof S>;
// StringSchemaBuilder<string, true>
Copy

Limitations