@topol/form-schemas

Zod v4 schemas for the Topol form JSON model: forms, steps, elements, and the Campaign/Variant/targeting/trigger contract used for popup targeting and A/B testing. Built on zod/mini for a smaller runtime footprint.

Install

npm install @topol/form-schemas zod

zod (^4.1.11) is a peer dependency, not bundled.

What's in here

• Form schemas — FormSchema, StepSchema, FormElementSchema, and the per-element-type property schemas, describing the full form JSON tree rendered by the Topol form widget.
• Campaign schemas — CampaignItemSchema, VariantSchema, CampaignTargetingSchema, TriggerConditionSchema, and CampaignItemsFileSchema, describing one independently-evaluated CampaignItem's targeting rules, display trigger, and A/B variants (there is no Campaign wrapper -- CampaignItem is the atomic authored/published unit, ADR 0025).

Usage

import { CampaignItemSchema } from "@topol/form-schemas";

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

Generating JSON Schema

Both schema families can be serialized to standard JSON Schema (draft 2020-12), for validating payloads from non-TypeScript consumers or for feeding an LLM the exact shape of valid JSON:

import { getFormJsonSchema, getCampaignItemJsonSchema } from "@topol/form-schemas";

const formSchema = getFormJsonSchema();
const campaignItemSchema = getCampaignItemJsonSchema();

The generated CampaignItem JSON Schema also ships pre-built in the package at schema/campaignItem.schema.json, so non-TypeScript consumers (e.g. a backend service in another language) can validate against the exact same contract without needing to run TypeScript or zod themselves.

Versioning

This package's semver is independent from the version/formatVersion fields inside the campaign/form JSON payloads themselves. Those in-payload fields describe wire-format migration compatibility at runtime; this package's version describes the TypeScript contract's own API compatibility. A bump in one doesn't imply a bump in the other.

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.