Skip to content
Docs menu

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.

View .md

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> or jump 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.