@formspec/core

Shared types, canonical IR nodes, and extension registration APIs for FormSpec.

Install

pnpm add @formspec/core

Most app code should prefer formspec unless you are building tooling, extensions, or lower-level integrations.

Main Responsibilities

Form element and state types
Canonical IR types used by the build pipeline
Constraint-definition metadata
Extension registration helpers for custom types, constraints, and annotations
Shared type guards

Example

import type { FormElement, FormIR } from "@formspec/core";
import { defineConstraint, defineCustomType, defineExtension } from "@formspec/core";

function isFieldElement(element: FormElement): boolean {
  return element._type === "field";
}

const decimalType = defineCustomType({
  typeName: "Decimal",
  tsTypeNames: ["Decimal"],
  toJsonSchema: (_payload, vendorPrefix) => ({
    type: "string",
    [`${vendorPrefix}-decimal`]: true,
  }),
});

const extension = defineExtension({
  extensionId: "x-example/decimal",
  types: [decimalType],
  constraints: [],
  annotations: [],
});

Key Exports

Form Types

FormSpec
FormElement
AnyField
Group
Conditional
FieldState
FormState

IR Types

FormIR
FieldNode
LayoutNode
TypeNode
ConstraintNode
AnnotationNode
Provenance

Extension API

defineExtension
defineConstraint
defineConstraintTag
defineAnnotation
defineCustomType

Utilities

normalizeConstraintTagName
createInitialFieldState
IR_VERSION
field and layout type guards

Entry Points

Entry point	Purpose
`@formspec/core`	Stable public types and extension APIs
`@formspec/core/internals`	Unstable low-level internal types

License

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