JSON Schema builder

Drag a field to any depth, select ten and move them together, add your own types. Four presets over one set of parts, and the keywords it has no UI for survive the round trip untouched.

@
@
@
@optional
@3 optionsoptional
@
@
@
@2 fieldsoptional
@
@optional
@[ ]optional
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "title": "ID",
      "description": "Unique numeric identifier"
    },
    "fullName": {
      "type": "string",
      "title": "Full name",
      "examples": [
        "Ada Lovelace"
      ]
    },
    "email": {
      "type": "string",
      "format": "email",
      "title": "Email"
    },
    "active": {
      "type": "boolean",
      "title": "Active"
    },
    "role": {
      "type": "string",
      "oneOf": [
        {
          "const": "admin",
          "title": "Admin"
        },
        {
          "const": "editor",
          "title": "Editor"
        },
        {
          "const": "viewer",
          "title": "Viewer"
        }
      ],
      "title": "Role"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string",
          "title": "Street"
        },
        "city": {
          "type": "string",
          "title": "City"
        }
      },
      "required": [
        "street"
      ],
      "additionalProperties": false,
      "title": "Address"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "title": "Tags"
      },
      "title": "Tags"
    }
  },
  "required": [
    "id",
    "fullName",
    "email"
  ],
  "additionalProperties": false
}

Installation

bunx --bun shadcn@latest add https://oss.flikk.dev/ui/r/json-editor.json

Usage

import { JsonSchemaEditor, useJsonSchema } from "@/components/ui/json/editor"
export function Fields({ initial }) {
  // a handle, not a value: it never re-renders this component
  const schema = useJsonSchema(initial)

  return (
    <>
      <JsonSchemaEditor schema={schema} variant="default" />
      <button onClick={() => save(schema.toJSON())}>Save</button>
    </>
  )
}

Composition

Schema.Root
├── Schema.Toolbar              shown while a selection is active
│   ├── Schema.SelectAll
│   ├── Schema.SelectionCount
│   └── SchemaAction.*          runs against the selection
├── Schema.List
│   ├── Schema.Column           a gutter every row lines up in
│   ├── Schema.Skeleton         the slot a dragged row will land in
│   └── SchemaField.Row         your row, drawn once
│       ├── SchemaAction.Drag
│       ├── SchemaAction.ChangeType
│       ├── SchemaField.Title
│       ├── SchemaField.Key
│       ├── SchemaField.Optional | Repeated | Nullable
│       ├── SchemaField.Menu
│       │   └── SchemaAction.*  runs against this field
│       └── SchemaField.Nested          groups only
│           ├── SchemaField.NestedToggle
│           ├── SchemaField.NestedSummary
│           └── SchemaField.NestedList  the same row, one level down
└── Schema.AddField

The row is written once. A group hands it to its own children through NestedList, so depth costs nothing and a row never learns how far down it is.

The whole tree is one CSS grid and every list a subgrid, which is what lets a declared Column line up at every depth: a checkbox on a field nested three deep sits in the same gutter as one at the top.

Examples

Variants

Four heads over one core. The handle does not know which is on, so switching costs nothing and a touch device gets the mobile one on its own.

@
@optional
@1 fieldoptional
@optional

Parts

When the preset is not the shape you want, compose it. This is the preset's own row, written out: the same parts, arranged differently.

@
@optional
@optional
@optional

Your own types

A type is one object. Add it to the handle and rows, menus and the type picker pick it up, because nothing inside branches on the type name.

@optional
@optional

API reference

useJsonSchema(json, { types?, slugCase? })   // a stable handle
  schema.toJSON()        // read, on save
  schema.toExample()     // an example document
  schema.subscribe(fn)   // listen
  schema.reset(json)     // replace
  schema.selected()      // ids
useJsonSchemaValue(schema)   // opt in to re-rendering on every change

A handle, not value and onChange. Rows subscribe to their own node and the owner subscribes to nothing, so typing in one field does not re-render the page around it. Ask for the value when you need it, or opt in with useJsonSchemaValue.

<JsonSchemaEditor schema variant="default | compact | wide | mobile" portalContainer />

useSchema()   // { schema, setSchema, fields, selectedFields, issues, types, toJSON, toExample }
useField()    // { field, type, update, drop, duplicate, childrenCount, issue, selected, select }

The built-in parts are written on these two hooks and nothing else, so a row of your own has everything the shipped one had.

defineType({
  key, icon, label, description, color,
  schema:   (node) => object,     // to JSON Schema
  example:  (node) => unknown,    // to an example document
  children: boolean,              // group or leaf
  accepts?: string[] | true,      // what may be dropped inside
  examples?: boolean,
  countLabel?: (node) => string,
  Extra?:   (props) => ReactNode, // UI the type owns
})

Draft 2020-12 in and out. Keywords the editor has no UI for stay on the field and come back untouched, so a schema does not lose anything by being opened here.