json-render/packages/core

@json-render/core

Core library for json-render. Define schemas, create catalogs, generate AI prompts, and stream specs.

Installation

npm install @json-render/core zod

Key Concepts

• Schema: Defines the structure of specs and catalogs
• Catalog: Maps component/action names to their definitions with Zod props
• Spec: JSON output from AI that conforms to the schema
• SpecStream: JSONL streaming format for progressive spec building

Quick Start

Define a Schema

import { defineSchema } from "@json-render/core";

export const schema = defineSchema((s) => ({
  spec: s.object({
    root: s.object({
      type: s.ref("catalog.components"),
      props: s.propsOf("catalog.components"),
      children: s.array(s.string()), // Element keys (flat spec format)
    }),
  }),
  catalog: s.object({
    components: s.map({
      props: s.zod(),
      description: s.string(),
    }),
    actions: s.map({
      description: s.string(),
    }),
  }),
}), {
  promptTemplate: myPromptTemplate, // Optional custom AI prompt generator
});

Create a Catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "./schema";
import { z } from "zod";

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({
        title: z.string(),
        subtitle: z.string().nullable(),
      }),
      description: "A card container with title",
    },
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(["primary", "secondary"]).nullable(),
      }),
      description: "A clickable button",
    },
  },
  actions: {
    submit: { description: "Submit the form" },
    cancel: { description: "Cancel and close" },
  },
});

Generate AI Prompts

// Generate system prompt for AI
const systemPrompt = catalog.prompt();

// With custom rules
const systemPrompt = catalog.prompt({
  system: "You are a dashboard builder.",
  customRules: [
    "Always include a header",
    "Use Card components for grouping",
  ],
});

Stream AI Responses (SpecStream)

The SpecStream format uses JSONL patches to progressively build specs:

import { createSpecStreamCompiler } from "@json-render/core";

// Create a compiler for your spec type
const compiler = createSpecStreamCompiler<MySpec>();

// Process streaming chunks from AI
while (streaming) {
  const chunk = await reader.read();
  const { result, newPatches } = compiler.push(chunk);
  
  if (newPatches.length > 0) {
    // Update UI with partial result
    setSpec(result);
  }
}

// Get final compiled result
const finalSpec = compiler.getResult();

SpecStream format uses RFC 6902 JSON Patch operations (each line is a patch):

{"op":"add","path":"/root","value":"card-1"}
{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Hello"},"children":["btn-1"]}}
{"op":"add","path":"/elements/btn-1","value":{"type":"Button","props":{"label":"Click"},"children":[]}}

All six RFC 6902 operations are supported: add, remove, replace, move, copy, test.

Low-Level Utilities

import {
  parseSpecStreamLine,
  applySpecStreamPatch,
  compileSpecStream,
} from "@json-render/core";

// Parse a single line
const patch = parseSpecStreamLine('{"op":"add","path":"/root","value":{}}');
// { op: "add", path: "/root", value: {} }

// Apply a patch to an object
const obj = {};
applySpecStreamPatch(obj, patch);
// obj is now { root: {} }

// Compile entire JSONL string at once
const spec = compileSpecStream<MySpec>(jsonlString);

API Reference

Schema

Export	Purpose
defineSchema(builder, options?)	Create a schema with spec/catalog structure
SchemaBuilder	Builder with s.object(), s.array(), s.map(), etc.

Schema options:

Option	Purpose
promptTemplate	Custom AI prompt generator
defaultRules	Default rules injected before custom rules in prompts
builtInActions	Actions always available at runtime, auto-injected into prompts (e.g. setState)

Catalog

Export	Purpose
defineCatalog(schema, data)	Create a type-safe catalog from schema
catalog.prompt(options?)	Generate AI system prompt

SpecStream

Export	Purpose
createSpecStreamCompiler<T>()	Create streaming compiler
parseSpecStreamLine(line)	Parse single JSONL line
applySpecStreamPatch(obj, patch)	Apply patch to object
compileSpecStream<T>(jsonl)	Compile entire JSONL string

Dynamic Props

Export	Purpose
resolvePropValue(value, ctx)	Resolve a single prop expression
resolveElementProps(props, ctx)	Resolve all prop expressions in an element
PropExpression<T>	Type for prop values that may contain expressions
ComputedFunction	Function signature for $computed expressions
PropResolutionContext	Context for resolving props (includes functions for $computed)

Validation

Export	Purpose
check.required()	Required validation helper
check.email()	Email validation helper
check.matches(path)	Cross-field match helper
check.equalTo(path)	Cross-field equality helper
check.lessThan(path)	Cross-field less-than helper
check.greaterThan(path)	Cross-field greater-than helper
check.requiredIf(path)	Conditional required helper
builtInValidationFunctions	All built-in validation functions
runValidationCheck()	Run a single validation check

User Prompt

Export	Purpose
buildUserPrompt(options)	Build a user prompt with optional spec refinement and state context
buildEditUserPrompt(options)	Build a user prompt for editing an existing spec (used internally by buildUserPrompt)
buildEditInstructions(config, format)	Generate the prompt section describing available edit modes
isNonEmptySpec(spec)	Check whether a spec has a root and at least one element
UserPromptOptions	Options type for buildUserPrompt
EditMode	"patch" \| "merge" \| "diff"
EditConfig	Configuration for edit modes ({ modes: EditMode[] })
BuildEditUserPromptOptions	Options type for buildEditUserPrompt

Merge and Diff

Export	Purpose
deepMergeSpec(base, patch)	RFC 7396 deep merge (null deletes, arrays replace, objects recurse)
diffToPatches(oldObj, newObj)	Generate RFC 6902 JSON Patch operations from object diff

Spec Validation

Export	Purpose
validateSpec(spec, options?)	Validate spec structure and return issues
autoFixSpec(spec)	Auto-fix common spec issues (returns corrected copy)
formatSpecIssues(issues)	Format validation issues as readable strings

Actions

Export	Purpose
ActionBinding	Action binding with action, params, confirm, preventDefault, etc.
BuiltInAction	Built-in action definition with name and description

Inline Mode (Mixed Streams)

Export	Purpose
createJsonRenderTransform()	TransformStream that separates text from JSONL patches in a mixed stream
pipeJsonRender()	Server-side helper to pipe a mixed stream through the transform
SPEC_DATA_PART / SPEC_DATA_PART_TYPE	Constants for filtering spec data parts

The transform splits text blocks around spec data by emitting text-end/text-start pairs, ensuring the AI SDK creates separate text parts and preserving correct interleaving of prose and UI in message.parts.

State Store

Export	Purpose
createStateStore(initialState?)	Create a framework-agnostic in-memory StateStore
StateStore	Interface for plugging in external state management (Redux, Zustand, XState, etc.)
StateModel	State model type (Record<string, unknown>)

The StateStore interface allows renderers to use external state management instead of the built-in internal store:

import { createStateStore, type StateStore } from "@json-render/core";

// Simple in-memory store
const store = createStateStore({ count: 0 });

store.get("/count");          // 0
store.set("/count", 1);       // updates and notifies subscribers
store.getSnapshot();          // { count: 1 }

// Subscribe to changes (compatible with React's useSyncExternalStore)
const unsubscribe = store.subscribe(() => {
  console.log("state changed:", store.getSnapshot());
});

Pass the store to StateProvider in any renderer package (@json-render/react, @json-render/react-native, @json-render/react-pdf) for controlled mode.

Store Utilities (for adapter authors)

Available via @json-render/core/store-utils:

Export	Purpose
createStoreAdapter(config)	Build a full StateStore from a minimal { getSnapshot, setSnapshot, subscribe } config
immutableSetByPath(root, path, value)	Immutably set a value at a JSON Pointer path with structural sharing
flattenToPointers(obj)	Flatten a nested object into JSON Pointer keyed entries
StoreAdapterConfig	Config type for createStoreAdapter

import { createStoreAdapter, immutableSetByPath, flattenToPointers } from "@json-render/core/store-utils";

createStoreAdapter handles get, set (with no-op detection), batched update, getSnapshot, getServerSnapshot, and subscribe -- adapter authors only need to supply the snapshot source, write API, and subscribe mechanism:

import { createStoreAdapter } from "@json-render/core/store-utils";

const store = createStoreAdapter({
  getSnapshot: () => myLib.getState(),
  setSnapshot: (next) => myLib.setState(next),
  subscribe: (listener) => myLib.subscribe(listener),
});

The official adapter packages (@json-render/redux, @json-render/zustand, @json-render/jotai) are all built on top of createStoreAdapter.

Types

Export	Purpose
Spec	Base spec type
Catalog	Catalog type
BuiltInAction	Built-in action type (name + description)
ComputedFunction	Function signature for $computed expressions
VisibilityCondition	Visibility condition type (used by $cond)
VisibilityContext	Context for evaluating visibility and prop expressions
SpecStreamLine	Single patch operation
SpecStreamCompiler	Streaming compiler interface

Dynamic Prop Expressions

Any prop value can be a dynamic expression that resolves based on data state at render time. Expressions are resolved by the renderer before props reach components.

Data Binding ($state)

Read a value directly from the state model:

{
  "color": { "$state": "/theme/primary" },
  "label": { "$state": "/user/name" }
}

Two-Way Binding ($bindState / $bindItem)

Use { "$bindState": "/path" } on the natural value prop for form components that need read/write access. The component reads from and writes to the state path:

{
  "type": "Input",
  "props": {
    "value": { "$bindState": "/form/email" },
    "placeholder": "Email"
  }
}

Inside a repeat scope, use { "$bindItem": "completed" } to bind to a field on the current item:

Conditional ($cond / $then / $else)

Evaluate a condition (same syntax as visibility conditions) and pick a value:

{
  "color": {
    "$cond": { "$state": "/activeTab", "eq": "home" },
    "$then": "#007AFF",
    "$else": "#8E8E93"
  },
  "name": {
    "$cond": { "$state": "/activeTab", "eq": "home" },
    "$then": "home",
    "$else": "home-outline"
  }
}

$then and $else can themselves be expressions (recursive):

{
  "label": {
    "$cond": { "$state": "/user/isAdmin" },
    "$then": { "$state": "/admin/greeting" },
    "$else": "Welcome"
  }
}

Repeat Item ($item)

Inside children of a repeated element, read a field from the current array item:

{ "$item": "title" }

Use "" to get the entire item object. $item takes a path string because items are typically objects with nested fields to navigate.

Repeat Index ($index)

Get the current array index inside a repeat:

{ "$index": true }

$index uses true as a sentinel flag because the index is a scalar value with no sub-path to navigate (unlike $item which needs a path).

Template ($template)

Interpolate state values into strings using ${/path} syntax:

{
  "label": { "$template": "Hello, ${/user/name}! You have ${/inbox/count} messages." }
}

Missing paths resolve to an empty string.

Computed ($computed)

Call a registered function with resolved arguments:

{
  "text": {
    "$computed": "fullName",
    "args": {
      "first": { "$state": "/form/firstName" },
      "last": { "$state": "/form/lastName" }
    }
  }
}

Functions are registered in the catalog and provided at runtime via the functions prop on the renderer.

import type { ComputedFunction } from "@json-render/core";

const functions: Record<string, ComputedFunction> = {
  fullName: (args) => `${args.first} ${args.last}`,
};

API

import { resolvePropValue, resolveElementProps } from "@json-render/core";

// Resolve a single value
const color = resolvePropValue(
  { $cond: { $state: "/active", eq: "yes" }, $then: "blue", $else: "gray" },
  { stateModel: myState }
);

// Resolve all props on an element
const resolved = resolveElementProps(element.props, { stateModel: myState });

Visibility Conditions

Visibility conditions control when elements are shown. VisibilityContext is { stateModel: StateModel, repeatItem?: unknown, repeatIndex?: number }.

Syntax

{ "$state": "/path" }                          // truthiness
{ "$state": "/path", "not": true }             // falsy
{ "$state": "/path", "eq": value }             // equality
{ "$state": "/path", "neq": value }            // inequality
{ "$state": "/path", "gt": number }            // greater than
{ "$item": "field" }                          // repeat item field
{ "$index": true, "gt": 0 }                   // repeat index
[ condition, condition ]                       // implicit AND
{ "$and": [ condition, condition ] }           // explicit AND
{ "$or": [ condition, condition ] }            // OR
true / false                                   // always / never

TypeScript Helpers

import { visibility } from "@json-render/core";

visibility.always              // true
visibility.never               // false
visibility.when("/path")       // { $state: "/path" }
visibility.unless("/path")     // { $state: "/path", not: true }
visibility.eq("/path", val)    // { $state: "/path", eq: val }
visibility.neq("/path", val)   // { $state: "/path", neq: val }
visibility.gt("/path", n)      // { $state: "/path", gt: n }
visibility.gte("/path", n)     // { $state: "/path", gte: n }
visibility.lt("/path", n)      // { $state: "/path", lt: n }
visibility.lte("/path", n)     // { $state: "/path", lte: n }
visibility.and(cond1, cond2)   // { $and: [cond1, cond2] }
visibility.or(cond1, cond2)    // { $or: [cond1, cond2] }

User Prompt Builder

Build structured user prompts for AI generation, with support for refinement and state context:

import { buildUserPrompt } from "@json-render/core";

// Fresh generation
const prompt = buildUserPrompt({ prompt: "create a todo app" });

// Refinement with edit modes (default: patch-only)
const refinementPrompt = buildUserPrompt({
  prompt: "add a dark mode toggle",
  currentSpec: existingSpec,
  editModes: ["patch", "merge"],
});

// With runtime state context
const contextPrompt = buildUserPrompt({
  prompt: "show my data",
  state: { todos: [{ text: "Buy milk" }] },
});

When currentSpec is provided, the prompt instructs the AI to use the specified edit modes. Available modes:

• "patch" — RFC 6902 JSON Patch. One operation per line. Best for precise, targeted single-field updates.
• "merge" — RFC 7396 JSON Merge Patch. Partial object deep-merged; null deletes. Best for structural changes.
• "diff" — Unified diff against the serialized spec. Best for small text-level changes.

Deep Merge and Diff

Format-agnostic utilities for working with specs:

import { deepMergeSpec, diffToPatches } from "@json-render/core";

// RFC 7396 deep merge: null deletes, arrays replace, objects recurse
const merged = deepMergeSpec(baseSpec, { elements: { main: { props: { title: "New" } } } });

// RFC 6902 diff: generate JSON Patch operations from two objects
const patches = diffToPatches(oldSpec, newSpec);
// [{ op: "replace", path: "/elements/main/props/title", value: "New" }]

Spec Validation

Validate spec structure and auto-fix common issues:

import { validateSpec, autoFixSpec, formatSpecIssues } from "@json-render/core";

// Validate a spec
const { valid, issues } = validateSpec(spec);

// Format issues for display
console.log(formatSpecIssues(issues));

// Auto-fix common issues (returns a corrected copy)
const fixed = autoFixSpec(spec);

State Watchers

Elements can declare a watch field to trigger actions when state values change. watch is a top-level field on the element (sibling of type, props, children), not inside props.

{
  "type": "Select",
  "props": {
    "label": "Country",
    "value": { "$bindState": "/form/country" },
    "options": ["US", "Canada", "UK"]
  },
  "watch": {
    "/form/country": {
      "action": "loadCities",
      "params": { "country": { "$state": "/form/country" } }
    }
  },
  "children": []
}

Watchers only fire on value changes, not on initial render. Multiple action bindings per path execute sequentially.

Validation

Built-in Validation Functions

Function	Description	Args
required	Value must not be empty	—
email	Must be a valid email	—
url	Must be a valid URL	—
numeric	Must be a number	—
minLength	Minimum string length	{ min: number }
maxLength	Maximum string length	{ max: number }
min	Minimum numeric value	{ min: number }
max	Maximum numeric value	{ max: number }
pattern	Must match regex	{ pattern: string }
matches	Must equal another field	{ other: { $state: "/path" } }
equalTo	Alias for matches	{ other: { $state: "/path" } }
lessThan	Must be less than another field	{ other: { $state: "/path" } }
greaterThan	Must be greater than another field	{ other: { $state: "/path" } }
requiredIf	Required when condition is truthy	{ field: { $state: "/path" } }

TypeScript Helpers

import { check } from "@json-render/core";

check.required("Field is required");
check.email("Invalid email");
check.matches("/form/password", "Passwords must match");
check.equalTo("/form/password", "Passwords must match");
check.lessThan("/form/endDate", "Must be before end date");
check.greaterThan("/form/startDate", "Must be after start date");
check.requiredIf("/form/enableNotifications", "Required when notifications enabled");

Custom Schemas

json-render supports completely different spec formats for different renderers:

// React: Flat element map
{ root: "card-1", elements: { "card-1": { type: "Card", props: {...}, children: [...] } } }

// Remotion: Timeline
{ composition: {...}, tracks: [...], clips: [...] }

// Your own: Whatever you need
{ pages: [...], navigation: {...}, theme: {...} }

Each renderer defines its own schema with defineSchema() and its own prompt template.