formspec

Umbrella package for the common FormSpec authoring and runtime APIs.

It re-exports the most commonly used pieces from:

• @stripe/formspec-core
• @stripe/formspec-dsl
• @stripe/formspec-build
• @stripe/formspec-runtime

It does not include the CLI, ESLint plugin, or language server.

Install

pnpm add @stripe/formspec

Quick start

import {
  buildFormSchemas,
  defineResolvers,
  field,
  formspec,
  group,
  is,
  type InferFormSchema,
  when,
} from "@stripe/formspec";

const OrderForm = formspec(
  group(
    "Order",
    field.text("customerName", { required: true }),
    field.enum("status", ["draft", "submitted"] as const, { required: true })
  ),
  when(is("status", "submitted"), field.text("submittedBy"))
);

type OrderData = InferFormSchema<typeof OrderForm>;

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

const resolvers = defineResolvers(OrderForm, {});

What you get

DSL

• formspec
• field
• group
• when
• is
• formspecWithValidation
• validateForm

Build

• buildFormSchemas
• generateJsonSchema
• generateUiSchema
• writeSchemas

Runtime

• defineResolvers

Types

• InferSchema
• InferFormSchema
• core field, layout, and state types
• resolver and validation helper types

Utilities

• createInitialFieldState
• validateForm
• logValidationIssues

When to use individual packages

• Use @stripe/formspec-build directly for generateSchemas(), generateSchemasFromClass(), generateSchemasFromProgram(), buildMixedAuthoringSchemas(), and static TypeScript analysis.
• Use @stripe/formspec-eslint-plugin for lint rules.
• Use @stripe/formspec-cli for build-time artifact generation from files.
• Use @stripe/formspec-validator for runtime JSON Schema validation.

License

This package is part of the FormSpec monorepo and is released under the MIT License. See LICENSE for details.