SEED

Seed BEFORE building the form UI. This is the one vertical that does not run in parallel with the client: the page renders the fields this creates, and imports the id it returns.

Additive only — an existing form with the same name is left exactly as it is and reported with created: false. Re-running never makes a second copy and never edits one.

Run

Plan

Form keys

Field keys

Kinds

text · textarea · email · phone · url · firstName · lastName · company · date · time · datetime · number · rating · select · radio · multi · tags · checkbox · file · address

email, phone, firstName, lastName, company are the CONTACTS kinds — Wix maps them onto the owner’s CRM contact, so prefer them over a plain text field for those.

A required address requires country, address line, city and postal code; parts overrides that per subfield.

Limits

The site’s plan caps the forms. A free site allows 4 forms, 10 fields per form, 3 steps and 3 rules; a paid plan lifts them. The seed reads the live limits (Get Restrictions) and checks the whole plan against them before creating anything, naming each form and the cap it breaks; nothing is created. Trim the form, or the owner upgrades the plan (https://www.wix.com/upgrade/website?metaSiteId=<siteId>) and the same plan runs unchanged. Do not split one form in two to fit: it spends a form slot and splits a visitor’s answers across two records. The example above sits at nine fields on purpose.

file needs a paid site plan. Verified live: on a free site the create fails as a whole with FILE_UPLOAD_RESTRICTIONS_ERROR (the seed reports it by field label; nothing is created). No API call lifts it — the owner upgrades the site in the dashboard, then the same plan runs unchanged. When the brief needs the upload now and the site is free, use a url kind for that field and add a capabilities.mediaUpload policy to the plan with "audience": "visitors" (Astro stack only; a policy admits logged-in members only unless it says so): the site uploads the file itself through the shared endpoint and submits the uploaded file’s URL as the field’s value. Say which way you went in the closing message; a “link to your CV” text field is not a substitute for an upload.

Rules

A rule shows, hides or requires fields while a condition on another field holds — the dashboard’s Rules tab, written as data. when names the deciding field by label and ONE test:

Effects: show: [labels] (those fields are created hidden and appear while the condition holds), hide: [labels], require: [labels]. A field a rule hides is cleared and not submitted.

Result

formId is what the page imports. fields[].target is each input’s name — the page does not need them (it renders form.fields from the live schema), but they are the keys the owner’s submissions are stored under.

degraded must be empty. It is the read-back check: the seed re-reads the created form and compares each field’s componentType against what it sent, and the step and rule counts. A non-empty list means something was accepted and then stored as something else — almost always a choice field that lost its options and became a plain text box. Fix the plan, delete nothing, and create the form again under a new name; a 200 on create does not mean the field survived.

What the seed does

1. Installs the Wix Forms app (idempotent).
2. Lists existing forms in the wix.form_app.form namespace — a name match is skipped.
3. Expands each field, builds the steps and rules, creates the form, reads it back and checks every componentType, the step count and the rule count.

Traps this seed already handles

Listed because a hand-rolled payload hits all of them, and each returns 200 first:

• A choice field declares its options twice — the component’s options[] and the validation enum (or items: { itemType, stringOptions.enum } for a multi). Disagree and the field is created as a plain text box. With an other entry no enum is written: the free text is by definition outside the list. For a multi, itemType sits inside items beside the options block; one level up the create is a 400 whose message blames the options block.
• A rule’s expression root is an and / or group, even for one condition. A bare condition at the root is a 400 (UNGROUPED_RULE_EXPRESSION_ROOT). Every condition carries a value, isEmpty / isNotEmpty / checked included (RULE_CONDITION_VALUE_MISSING without).
• validation must be present even when empty, nested under the input-type block, not the component one. Absent, the target is not registered as an accepted value and every submission is rejected with UNKNOWN_VALUE_ERROR on a key that IS in the schema.
• required lives at inputOptions.required, never inside a validation block. A checkbox that must be ticked additionally needs validation.enum: [true] — required alone only checks that a value is present, and false is a value.
• The prefill key differs per component: options[].default on a choice, checked on a checkbox, defaultValue on a rating, default elsewhere. The wrong key is silently ignored.
• Date bounds live under the format’s own block (dateOptions / timeOptions / dateTimeOptions), as strings, and accept $now±N.
• steps must reference every field, the submit button included. A field missing from the layout never appears in the owner’s dashboard — they cannot edit what the site renders.
• Rules reference fields by id (fieldOptions.fieldId, condition target), so a rule written by hand against labels never fires.
• target is immutable and must be unique within the form: letters, digits and single underscores, starting with a letter.
• A checkbox label is rich content (Ricos), not a string — the owner may put a link to the terms in it. The app flattens it to text.
• Use formFields, never fields — the latter is the legacy API.
• A file field fails the whole create on a free site (FILE_UPLOAD_RESTRICTIONS_ERROR, a plan restriction, not a payload bug); the seed names the field and the two ways out.

Supplied content

The general rules are in templates/shared/SUPPLIED-CONTENT.md. For forms the user usually hands over the form itself: a list of questions, or a PDF or screenshot of the form they use today. Each question becomes a field, with the kind its answer implies (an email address → email, a fixed set of answers → select, radio or multi, a long answer → textarea, an attachment → file); a required mark becomes required; “if yes, …” becomes a rule; page breaks become steps; the button label becomes submitText; the confirmation wording becomes thankYou. Question wording verbatim.