json-schema-effect

Effect library for JSON Schema generation, validation, and TOML tooling annotations (Tombi/Taplo) built on Effect Schema.

What is json-schema-effect?

json-schema-effect turns Effect Schema definitions into spec-compliant JSON Schema documents, validates them with Ajv strict mode, and writes the results to disk -- all within the Effect ecosystem. It also ships annotation helpers for Tombi and Taplo so generated schemas can power TOML editor autocompletion out of the box. Every capability is packaged as a composable service, so you adopt only what your application needs.

Features

• JsonSchemaExporter -- Generate JSON Schema from Effect Schema definitions with $ref inlining, artifact cleanup, and idempotent writes
• JsonSchemaValidator -- Validate generated schemas with Ajv strict mode for SchemaStore and Tombi compatibility
• JsonSchemaScaffolder -- Generate starter TOML/JSON config files from schema output with placeholder values, comments, and key ordering
• JsonSchemaClass -- Define self-describing schema classes that carry their own $id and schema entry metadata
• Jsonifiable -- Drop-in Schema.Unknown replacement that produces clean {} in JSON Schema output
• tombi / taplo -- Annotation helpers that embed TOML tooling metadata directly into your Effect Schema definitions
• scaffoldJson / scaffoldToml -- Pure scaffold helpers for generating config file strings without the Effect service layer

Quick Example

import { NodeFileSystem } from "@effect/platform-node";
import { Effect, Layer, Schema } from "effect";
import {
  JsonSchemaExporter,
  JsonSchemaValidator,
  JsonSchemaScaffolder,
  tombi,
} from "json-schema-effect";

const AppConfig = Schema.Struct({
  name: Schema.String,
  port: Schema.Number,
  debug: Schema.optional(Schema.Boolean),
});

const ExporterLayer = Layer.provide(JsonSchemaExporter.Live, NodeFileSystem.layer);
const ScaffolderLayer = Layer.provide(JsonSchemaScaffolder.Live, NodeFileSystem.layer);
const FullLayer = Layer.mergeAll(ExporterLayer, JsonSchemaValidator.Live, ScaffolderLayer);

const program = Effect.gen(function* () {
  const exporter = yield* JsonSchemaExporter;
  const validator = yield* JsonSchemaValidator;
  const scaffolder = yield* JsonSchemaScaffolder;

  // Generate and validate JSON Schema
  const output = yield* exporter.generate({
    name: "AppConfig",
    schema: AppConfig,
    rootDefName: "AppConfig",
    $id: "https://example.com/app-config.schema.json",
    annotations: { ...tombi({ tomlVersion: "v1.0.0", tableKeysOrder: "schema" }) },
  });
  yield* validator.validate(output, { strict: true });

  // Write JSON Schema to disk
  yield* exporter.write(output, "schemas/app-config.schema.json");

  // Scaffold a starter TOML config
  yield* scaffolder.writeScaffold(output, "app-config.toml", {
    format: "toml",
    commentOptional: true,
  });
});

Effect.runPromise(Effect.provide(program, FullLayer));

Install

npm install json-schema-effect effect @effect/platform

For writing schemas to disk, also install the platform-specific layer:

npm install @effect/platform-node

For JsonSchemaValidator, also install the optional peer dependency:

npm install ajv

Documentation

1. Getting Started
2. JSON Schema Generation
3. JSON Schema Advanced
4. Config Scaffolding
5. Testing
6. Error Handling
7. API Reference

API at a Glance

Services

| Export | Kind | Guide | | ------ | ---- | ----- | | JsonSchemaExporter | Context.Tag | JSON Schema Generation | | JsonSchemaValidator | Context.Tag | JSON Schema Advanced | | JsonSchemaScaffolder | Context.Tag | Config Scaffolding |

Schemas

| Export | Kind | Guide | | ------ | ---- | ----- | | Jsonifiable | Schema | JSON Schema Generation | | JsonSchemaClass | factory | JSON Schema Advanced | | Written | function | JSON Schema Generation | | Unchanged | function | JSON Schema Generation |

Helpers

| Export | Kind | Guide | | ------ | ---- | ----- | | tombi | function | JSON Schema Advanced | | taplo | function | JSON Schema Advanced | | scaffoldJson | function | Config Scaffolding | | scaffoldToml | function | Config Scaffolding |

Errors

| Export | Kind | Guide | | ------ | ---- | ----- | | JsonSchemaError | TaggedError | Error Handling | | JsonSchemaErrorBase | TaggedError base | Error Handling | | JsonSchemaValidationError | TaggedError | Error Handling | | JsonSchemaValidationErrorBase | TaggedError base | Error Handling | | ScaffoldError | TaggedError | Error Handling | | ScaffoldErrorBase | TaggedError base | Error Handling |

Types

| Export | Kind | Guide | | ------ | ---- | ----- | | JsonSchemaExporterService | type | JSON Schema Generation | | JsonSchemaValidatorService | type | JSON Schema Advanced | | JsonSchemaScaffolderService | type | Config Scaffolding | | ValidatorOptions | type | JSON Schema Advanced | | ScaffoldOptions | type | Config Scaffolding | | ScaffoldHelperOptions | type | Config Scaffolding | | JsonSchemaOutput | type | JSON Schema Generation | | SchemaEntry | type | JSON Schema Generation | | JsonSchemaClassStatics | type | JSON Schema Advanced | | TombiOptions | type | JSON Schema Advanced | | TaploOptions | type | JSON Schema Advanced | | WriteResult | type | JSON Schema Generation |

License

MIT