@cleverbrush/schema-json

fromJsonSchema(schema)

Converts a JSON Schema literal to a @cleverbrush/schema builder. Pass the schema with as const — this is required for TypeScript to infer precise builder and value types.

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

// Define the JSON Schema once — use as const for precise inference
const UserJsonSchema = {
  type: 'object',
  properties: {
    id:    { type: 'string', format: 'uuid' },
    name:  { type: 'string', minLength: 1, maxLength: 100 },
    email: { type: 'string', format: 'email' },
    age:   { type: 'integer', minimum: 0 },
    role:  { enum: ['admin', 'user', 'guest'] },
  },
  required: ['id', 'name', 'email'],
} as const;

// TypeScript infers the value type from the JSON Schema — no duplication!
type User = InferFromJsonSchema<typeof UserJsonSchema>;
// {
//   id: string;
//   name: string;
//   email: string;
//   age?: number;
//   role?: 'admin' | 'user' | 'guest';
// }

const UserSchema = fromJsonSchema(UserJsonSchema);

// Validate data — result.object is fully typed as User
const result = UserSchema.validate({
  id: 'a1b2c3d4-e5f6-1234-8abc-000000000001',
  name: 'Alice',
  email: 'alice@example.com',
  role: 'admin',
});

Supported JSON Schema keywords

toJsonSchema(schema, opts?)

Converts any @cleverbrush/schema builder to a JSON Schema object. Declarative constraints (formats, min/max, patterns, enum/const literals, required/optional per property) round-trip cleanly. Descriptions set via .describe(text) are emitted as the description field on the corresponding JSON Schema node.

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

const ProductSchema = object({
  sku:   string().uuid(),
  name:  string().minLength(1).maxLength(255),
  price: number().min(0),
  tags:  array(string()).optional(),
});

// Default: JSON Schema Draft 2020-12 with $schema header
const spec = toJsonSchema(ProductSchema);
// {
//   "$schema": "https://json-schema.org/draft/2020-12/schema",
//   "type": "object",
//   "properties": {
//     "sku":   { "type": "string", "format": "uuid" },
//     "name":  { "type": "string", "minLength": 1, "maxLength": 255 },
//     "price": { "type": "number", "minimum": 0 },
//     "tags":  { "type": "array", "items": { "type": "string" } }
//   },
//   "required": ["sku", "name", "price"]
// }

// Embed in an OpenAPI spec (suppress $schema header)
const openApiSchema = toJsonSchema(ProductSchema, { $schema: false });

// Use Draft 07 format
const draft7Schema = toJsonSchema(ProductSchema, { draft: '07' });

// Use nameResolver to emit $ref pointers for named component schemas
// (used internally by @cleverbrush/server-openapi — see SchemaRegistry)
const registry = new Map([['Product', ProductSchema]]);
const withRefs = toJsonSchema(ProductSchema, {
    $schema: false,
    nameResolver: (schema) => {
        for (const [name, s] of registry) {
            if (s === schema) return name;
        }
        return null;
    },
});
// Instead of inlining, nodes matching a registry entry become:
// { "$ref": "#/components/schemas/Product" }

Named references and local annotations

Ordinary use-site modifiers preserve a named definition. Direct reuse emits a $ref; modified uses compose local annotations and nullability around it in both Draft 7 and Draft 2020-12:

const User = object({ name: string() }).schemaName('User');
const History = object({
    current: User,
    previous: User.optional().nullable().describe('Previous user')
});
const json = toJsonSchema(History, {
    $schema: false,
    nameResolver: schema => schema.introspect().schemaName ?? null
});
// json.required: ['current']
// current references User; previous adds local description and nullability.

Use-site modifiers are processed before name resolution, which receives their canonical target. The resolver does not create component definitions: supply those in the containing document or use @cleverbrush/server-openapi. Without a resolver, the target is converted inline.

Shape, rule, default, fallback and extension changes discard inherited names and export inline. Nested named children still reuse their definitions. Apply schemaName after those edits to name a new definition. See the schema naming rules.

Standard JSON Schema input() and output() keep their existing identical representation; no separate directional schemas are introduced.

Limitations