Forms logic, outlines and instructions
How Venom Forms decides which questions a respondent sees, the markdown outline that creates a form, and the instructions that edit one safely.
One module, lib/forms/logic.ts, decides the path through a form. The builder's preview, the public page and the
server's check on submit all run it, so what a respondent sees is what the server accepts.
Rules
A rule is when conditions hold, then actions. Conditions combine with all or any. A condition tests one earlier
question (or a variable, written var:score) with an operator:
equals, notEquals, contains, notContains, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual,
isAnswered, isEmpty, startsWith, endsWith.
A choice is matched by its label or its id. Multiple choice uses contains. Hidden fields (filled from the link, such as
?utm_source=ad) can be tested like any question.
| Action | What it does | Rule |
|---|---|---|
show a block |
reveals a block marked "hidden until a rule shows it" | the block comes after every question the rule tests |
hide a block |
removes it from the path | same |
jump to a block or end |
skips ahead when the respondent leaves the question the rule is after |
forward only |
set a variable |
sets it to a number, or adds to it (scores, totals) | runs when leaving the after block, or once at the end |
Rules run in order and a later one wins. Required questions only count when they are on the respondent's path. A block hidden by logic is never asked, never validated and never stored.
Outlines
forms_form_create and the "Paste an outline" box take a short markdown outline:
# Customer feedback
Tell us how we did.
- Your name [short text] *
- How was it? [rating 1-5] *
- What went wrong? [long text]
- How did you hear about us? [single choice: A friend | An ad | Other]
if How was it? <= 2 then show What went wrong?
if How did you hear about us? = Other then ask: Tell us more- The first
#heading is the title; prose above the first question becomes the welcome text. - One
-line per question. A trailing*means required.[type]is optional (it is guessed from the words) and is one of: short text, long text, email, phone, url, number, yes/no, rating 1-5, scale 1-10, nps, date, file upload, ranking, single choice, multiple choice, dropdown, statement. Choices follow a colon, separated by|. - Rules are
if <question> <op> <value> then <action>. The question is named by the start of its text, or#2. Operators:=,!=,<,<=,>,>=,contains,is answered,is empty. Actions:show <q>,hide <q>,jump to <q>orjump to end,ask: <new question>,set score = 3,set score += 3. - A line it can't read is reported back as a warning; the rest still builds.
Instructions
Edits address blocks and rules by their stable ids, never by position, so two editors don't corrupt each other. A list
applies in order, all or none, and only if the form is still at the version you read (If-Match or expectVersion),
otherwise 409 version_conflict. A bad instruction is 422 invalid_instruction and names its index and the reason.
addBlock, updateBlock, moveBlock, removeBlock (rules that mention the block go with it), addRule, updateRule,
removeRule, reorderRules, setTitle, setSettings, publish, close. The full shapes are in the
MCP tool description and contracts/forms-openapi.yaml. The builder sends the same instructions.