@stripe/formspec-core

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

Install

pnpm add @stripe/formspec-core

Most app code should prefer @stripe/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 "@stripe/formspec-core";
import {
  defineAnnotation,
  defineConstraint,
  defineCustomType,
  defineExtension,
} from "@stripe/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 displayCurrency = defineAnnotation({
  annotationName: "DisplayCurrency",
  inheritFromBase: "local-wins",
});

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

inheritFromBase is semantic inheritance only. It lets a type-level custom annotation flow through class/interface heritage and named type-alias entry points when the derived declaration does not declare the same extension annotation locally, but it does not serialize the annotation to JSON Schema. Schema emission remains controlled by the optional existing toJsonSchema hook, so property-level annotation inheritance and metadata-slot inheritance remain out of scope.

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 | | -------------------------- | -------------------------------------- | | @stripe/formspec-core | Stable public types and extension APIs | | @stripe/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.