@topol/form-editor-schemas

Zod v4 schemas for the Topol Form Editor's host-facing contract — the options a Host App passes to TopolEditor.init(), the CampaignItem shape it loads and gets back on save, and the theme library it owns. Built on zod/mini for a smaller runtime footprint.

Install

npm install @topol/form-editor-schemas @topol/form-schemas zod

zod (^4.1.11) and @topol/form-schemas (^0.4.0) are peer dependencies, not bundled.

What's in here

• TopolFormEditorOptionsSchema — the whole init() contract: the mount target, locale, theme library, the item/items being edited, the file manager config, and every Host callback (onSave, onThemeSave, …).

• CampaignItemSchema / VariantSchema — the editor-facing item shape, carrying a resolved form rather than the wire schema's definition (the editor only ever holds real content to render, never a lazy {ref} pointer). Their envelope fields come straight from @topol/form-schemas' CampaignItemBaseSchema.

  form is nullable. Inbound, null means a brand-new, never-saved variant, and opens on a blank canvas. It is reachable outbound too, but only narrowly: onSave mirrors back what the editor holds for a variant it was handed and never asked to load: once a variant has been through load(), a blank canvas has been substituted and it never saves back null. A missing form key is rejected either way: an item carries form or variants, never neither.

• ThemeGroupSchema / ThemeEntrySchema / ThemeSavePayloadSchema — the Host-owned theme library and the payload the Theme Panel sends back to it.

• FileManagerOptionsSchema — an inlined mirror of @topol/image-picker's FileOptions, until that package gets a publish story of its own.

Usage

import {
  TopolFormEditorOptionsSchema,
  type TopolFormEditorOptions,
} from "@topol/form-editor-schemas";

const result = TopolFormEditorOptionsSchema.safeParse(options);
if (!result.success) {
  // result.error describes exactly which field failed and why
}

The editor validates both init()'s options and load()'s payload against these schemas at runtime and hard-stops on failure — it refuses to mount, or refuses to apply, and reports through the onError callback (plus a console.error, since onError is optional) rather than rendering a partially-broken editor.

Why this is separate from @topol/form-schemas

@topol/form-schemas describes the published campaign JSON — a stored artifact consumed by the form widget on customer sites and by backend publish jobs, which needs long-lived backward compatibility.

This package describes how a host boots the editor UI — a live integration surface, not a stored artifact, with a different audience and a different compatibility promise. One version number can't clearly signal both "is my published campaign JSON still valid" and "did my editor integration just break". The dependency runs one way only: this package peer-depends on @topol/form-schemas for Form/FormTheme, never the reverse.

Versioning

This package's version tracks the editor's own contract changes and is bumped in the same change that alters the contract. It is independent of @topol/form-schemas' version line.

Source

Part of the Topol editors monorepo, which is a private repository — the repository field above won't resolve for external visitors. This package is published publicly because its contents (schema shapes, no business logic or credentials) are safe to distribute even though the source repo isn't.