Schema Fabricator

Schema Fabricator generates JSON documents from composable class, enum, union, function, and state definitions. It supports nested structures, multilevel class inheritance, optional fields, recursive schemas, stateful functions, and coverage-aware generation.

Install

npm install schema-fabricator

For command-line use without adding it to a project:

npx schema-fabricator --help

Requires Node.js 20 or later.

Command line

After a global install, use the short sf command to create and operate a project:

npm install -g schema-fabricator
mkdir my-schema-project && cd my-schema-project
sf init
sf generate --yes
sf stats
sf gui

sf init creates sf-config.json, the definitions/ directory tree, and an empty Root class. It never overwrites an existing config or root class. sf stats reports definition counts, recursion status, possible-document count when finite, generated-document count and size, coverage-branch occurrences, and aggregate enum-value distribution. Occurrence statistics are saved with each sf generate run.

sf gui starts the local schema designer for the current project. It prints the local URL (normally http://localhost:4173); stop it with Ctrl+C.

Run the generator from a directory containing config.json and definitions/:

schema-fabricator --yes

When working from a Schema Fabricator project checkout, the equivalent npm script is:

npm run generate -- --yes

schema-fabricator [options]

  -c, --config <file>           Configuration file (default: config.json)
  -d, --definitions <directory> Definitions directory (default: definitions)
  -o, --output <directory>      Generated-document directory (default: generated)
  -y, --yes                     Generate without an interactive confirmation
  -h, --help                    Show help

The output directory is cleared only after confirmation (or --yes). Recursive schemas report that total-document estimation is skipped and are bounded by maxDepth.

Launch the local schema designer for the current project with:

schema-fabricator-gui

Set SCHEMA_FABRICATOR_PROJECT_ROOT to target a different project directory.

Project layout

config.json
definitions/
  classes/
    Article.class.json
    Article.class/
      Seo.class.json
  enums/
    Visibility.enum.json
  unions/
    Content.union.json
  functions/
    makeSlug.function.js
  state/
    Counters.state.json

Nested class files inherit their parent class. For example, Article.class/Seo.class.json inherits Article.class.json.

Configuration

{
  "root": "<class:Article>",
  "maxDepth": 4,
  "maxArrayLength": 3,
  "minOccurances": 1
}

minOccurances deliberately retains its existing spelling for compatibility with schema projects.

Definition syntax

Classes and nested objects use JSON object fields. A key ending in ? is optional.

{
  "title": "<String>",
  "visibility": "<enum:Visibility>",
  "related?": "[<union:Content>]",
  "metadata": {
    "featured": "<Boolean>"
  }
}

Supported values:

• Primitive tokens: <String>, <Number>, <Boolean>, <Null>
• References: <class:Name>, <enum:Name>, <union:Name>
• Functions: <function:name> or <function:name schema.class.Article>
• Array notation: "[<class:Name>]" or JSON arrays with one item
• Tuple notation: JSON arrays with multiple items
• Nested JSON objects and literal strings, numbers, booleans, and null

Enums and unions are JSON arrays:

["public", "private"]

["<class:Article>", "<class:Video>"]

Function files export (or declare) a function with the same name as the file. State files are mutable JSON objects shared by functions during one generation run.

Library API

const { Fabricator, generate, generateToDirectory } = require("schema-fabricator");

const fabricator = new Fabricator("./definitions", {
  maxDepth: 4,
  maxArrayLength: 3,
  minOccurances: 1,
});

const documents = fabricator.generate("<class:Article>");

// Or use config.json, definitions/, and generated/ in the current directory.
const documentsFromProject = generate();
generateToDirectory();

The root export also exposes DefinitionLoader, readJson, and parser helpers for advanced integrations.

Publishing this repository

Choose an npm package name you control, update the name field if necessary, then run:

npm login
npm run pack:check
npm publish

For a scoped public package, use npm publish --access public.

License

ISC