@formspec/build

Build tools to compile FormSpec forms into JSON Schema and JSON Forms UI Schema.

Installation

npm install @formspec/build
# or
pnpm add @formspec/build

Note: Most users should install the formspec umbrella package instead, which re-exports everything from this package.

Requirements

This package is ESM-only and requires:

// package.json
{
  "type": "module"
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Usage

Generate Schemas in Memory

import { buildFormSchemas } from "@formspec/build";
import { formspec, field, group } from "@formspec/dsl";

const ContactForm = formspec(
  field.text("name", { label: "Name", required: true }),
  field.text("email", { label: "Email", required: true }),
  field.enum("subject", ["General", "Support", "Sales"])
);

const { jsonSchema, uiSchema } = buildFormSchemas(ContactForm);

// Use with JSON Forms renderer
// <JsonForms schema={jsonSchema} uischema={uiSchema} data={formData} />

Write Schemas to Disk

import { writeSchemas } from "@formspec/build";

const result = writeSchemas(ContactForm, {
  outDir: "./generated",
  name: "contact-form",
  indent: 2,
});

console.log(`JSON Schema: ${result.jsonSchemaPath}`);
console.log(`UI Schema: ${result.uiSchemaPath}`);
// JSON Schema: ./generated/contact-form-schema.json
// UI Schema: ./generated/contact-form-uischema.json

Use Individual Generators

import { generateJsonSchema, generateUiSchema } from "@formspec/build";

const jsonSchema = generateJsonSchema(ContactForm);
const uiSchema = generateUiSchema(ContactForm);

Generated Output

JSON Schema (Draft-07)

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string", "title": "Name" },
    "email": { "type": "string", "title": "Email" },
    "subject": {
      "type": "string",
      "enum": ["General", "Support", "Sales"]
    }
  },
  "required": ["name", "email"]
}

JSON Forms UI Schema

{
  "type": "VerticalLayout",
  "elements": [
    { "type": "Control", "scope": "#/properties/name", "label": "Name" },
    { "type": "Control", "scope": "#/properties/email", "label": "Email" },
    { "type": "Control", "scope": "#/properties/subject" }
  ]
}

API Reference

Functions

Function	Description
`buildFormSchemas(form)`	Generate both JSON Schema and UI Schema
`generateJsonSchema(form)`	Generate only JSON Schema
`generateUiSchema(form)`	Generate only UI Schema
`writeSchemas(form, options)`	Build and write schemas to disk

Types

Type	Description
`BuildResult`	Return type of `buildFormSchemas`
`WriteSchemasOptions`	Options for `writeSchemas`
`WriteSchemasResult`	Return type of `writeSchemas`
`JSONSchema7`	JSON Schema Draft-07 type
`UISchema`	JSON Forms UI Schema type

License

UNLICENSED