---
title: Forms logic, outlines and instructions
description: How Venom Forms decides which questions a respondent sees, the markdown outline that creates a form, and the instructions that edit one safely.
section: cloud
order: 151
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/forms/logic.ts, services/nodejs-cloud/lib/forms/outline.ts, services/nodejs-cloud/lib/forms/instructions.ts, docs/adr/0056-venom-forms.md]
features: []
---

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:

```markdown
# 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](/docs/developers/forms.md#instructions) and `contracts/forms-openapi.yaml`. The builder sends the same instructions.
