Conditional Logic
Fields can be shown, hidden, or conditionally required based on the value or presence of other fields. Conditional logic works in every DocSpring form: simple web forms, visual forms, and signature requests. It is also enforced when you submit data via the API.
Adding a Condition to a Field
Section titled “Adding a Condition to a Field”- Select a field in the template editor.
- Scroll down to the Conditional Logic section.
- Click + Add Condition.
- Choose the Action, the source Field, an Operator, and a value (if the operator needs one).
You can add multiple conditions to a rule, and choose whether all or any of the conditions must match.
Actions
Section titled “Actions”- Show and Require: The field is only shown (and required) when the conditions match. This is the most common action.
- Show: The field is only shown when the conditions match. If the field’s own Required option is checked, it is “required when visible”.
- Require: The field is always shown, but only required when the conditions match.
Operators
Section titled “Operators”| Operator | Description |
|---|---|
| Is Present | The field has any non-blank value |
| Is Blank | The field is empty |
| Equals | The field’s value matches exactly |
| Does Not Equal | The field is blank, or has a different value |
| Is One Of | The field’s value matches one of the listed values |
| Greater, Greater or Equal, Less, Less or Equal | Numeric comparisons (for Number fields) |
| In Range | The value is within an inclusive numeric range |
The numeric operators are only available when the source field is a Number field. When the source field is a Boolean field, only Equals and Does Not Equal are available.
Applying a Condition to a Group of Fields
Section titled “Applying a Condition to a Group of Fields”Click an object group in the field list to apply one rule to every field in that group. This is useful for hiding a whole section — for example, hiding 24 “Dependent Information” fields when someone selects “decline coverage”:
- Source Field:
selected_coverage - Operator: Does Not Equal
- Value:
decline - Action: Show and Require
When “decline” is selected, every field in the group is hidden and none of them are required.
Array groups do not support group conditions.
A group rule belongs to its group and always applies to the group’s current fields: fields you add to the group in the template editor are included, fields you rename or move out of the group are no longer affected, and the rule is removed when the group no longer contains any fields. To keep a group rule while renaming the group, rename the group itself (click the group in the field list) rather than renaming its fields one by one.
Seeing All Rules
Section titled “Seeing All Rules”Click Logic in the template editor header to see every rule on the template in one place. You can add, change and remove rules there. Rules that belong to a field or a group are changed in that field’s or group’s options.
When AI sets up conditional logic (see Automatic Field Detection), each rule it added shows Why it was added. The Logic window also lists the formulas the AI added to fill in totals, and the fields it made required or optional, which you can Undo.
Behavior Details
Section titled “Behavior Details”- Hidden fields are never required. A required field that is hidden by a condition will not block form submission.
- Hidden field values are not submitted. If someone fills in a field and then a condition hides it, the value is excluded from the submitted data (and from the generated PDF). The typed value reappears if the condition shows the field again.
- Hidden fields are never rendered. Values for condition-hidden fields are also stripped on the server when a PDF is generated, so data submitted via the API renders exactly like a form submission. The stored submission data is not modified — only the rendered output.
- Conditions can be chained. A condition’s source field can itself be conditionally shown. A hidden source field always counts as blank.
- Default values count. When the data leaves out a field that has a default value, a condition on that field reads the default, as the forms do when they fill it in. This applies to generated PDFs and to the JSON schema that validates API submissions. A number default counts to 8 decimal places, as the visual form shows it.
- Conditions can use formulas. Formulas are calculated before conditions are checked, so a condition can use a formula field’s result. A formula field that a condition hides isn’t printed.
- Sample data respects conditions. Generated example data (API code examples, the template editor’s random test data) leaves out fields that would be hidden.
- Signature requests keep each signer’s conditions to themselves. A
condition can only use the sender’s data and the fields of the signer who
fills in the fields it shows, hides or requires, so one signer can’t change
what another signer saw and signed. API
v2 refuses to create signature
requests that break this, and names the field in a
422error.
JSON Schema Output
Section titled “JSON Schema Output”Conditional logic is expressed in your template’s JSON schema using standard
JSON Schema draft-07 if/then
conditionals, in the same shape that generic JSON Schema form renderers such as
react-jsonschema-form
understand — so you can render the schema directly with your own form library
(and the conditional fields will be shown, hidden, and required exactly like in
DocSpring’s forms), validate data with any JSON Schema validator, or hand the
schema to an AI agent that fills out your form.
- Conditionally shown fields are only defined inside the conditional. A
field that is shown by a condition (the Show and Show and Require actions)
is not defined in the base
properties: the base schema only contains an empty placeholder ({}) at the field’s position, and the field’s full definition lives in thethenbranch of its conditional in the top-levelallOf. When every field in an object group is shown by the same condition, the whole group is a single placeholder, and the group’s full definition lives in the conditional. The placeholder keeps the field’s position (so form renderers keep your field order when they merge thethenbranch into the schema), and keepsadditionalProperties: falseworking; any stale value for a hidden field is accepted (and ignored by DocSpring). - Conditionally required fields are listed in the
thenbranch’srequiredarray. Rule targets are never in the baserequiredarray, so data that omits hidden fields validates correctly. A Show field that is itself marked required is “required when visible”; a Require field (always visible) stays in the basepropertiesand its conditional only addsrequired. - Rules are combined per field, so a field hidden by one rule is never required by another, and a condition on a source field that is itself conditionally shown only matches while that source is visible (a hidden source counts as blank).
- Annotation: each dependent field’s definition carries an
x-field-dependenciesarray describing its rules in a machine-readable format (including arequiredWhenMatchedflag). The conditionals DocSpring generates are markedx-docspring-field-dependencies: true.
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "additionalProperties": false, "properties": { "coverage": { "type": "string", "enum": ["employee", "family", "decline"] }, "beneficiary": {} }, "required": ["coverage"], "allOf": [ { "if": { "required": ["coverage"], "properties": { "coverage": { "not": { "enum": [null, ""] }, "const": "family" } } }, "then": { "properties": { "beneficiary": { "type": "string", "title": "Beneficiary", "x-field-dependencies": [ { "action": "require_and_show", "match": "all", "conditions": [ { "field": "coverage", "operator": "equals", "value": "family" } ], "requiredWhenMatched": true } ] } }, "required": ["beneficiary"] }, "x-docspring-field-dependencies": true } ]}Configuring Conditions via the API
Section titled “Configuring Conditions via the API”Group rules are stored in the template’s field_dependencies array. You can set
them with the Update Template
endpoint, which replaces the whole array:
{ "field_dependencies": [ { "action": "require_and_show", "match": "all", "conditions": [ { "field": "coverage", "operator": "not_equals", "value": "decline" } ], "targets": ["dependent_name", "dependent_dob"] } ]}Per-field rules are each field’s dependencies. Set them with
Update a template’s fields,
with the field’s id from
List a template’s fields.
A rule applies to every field with the same name, and null removes it:
{ "fields": [ { "id": 12, "dependencies": { "action": "require_and_show", "match": "all", "conditions": [ { "field": "coverage", "operator": "equals", "value": "family" } ] } } ]}action:require_and_show,show, orrequirematch:alloranyoperator:present,blank,equals,not_equals,in,gt,gte,lt,lte, orrange(usevaluefor the lower bound andrange_maxfor the upper bound). The numeric operators (gt,gte,lt,lte,range) are only valid when the source field is a Number field, and require decimal numbers such as5,-1.5or1e3(rangeneeds at least one bound; a missing bound makes the range open-ended).- Field names use the same
a/b/cpath syntax as nested field names group(optional) marks a rule as authored on a field group in the template editor, where it is shown and edited on that group. Group rules only apply to the group’s fields: when the template is saved, targets outside<group>/(or that conditional logic cannot apply to, such as static fields) are removed from the rule, and the rule itself is removed once the group has no fields. Rules withoutgroupare stored as given.targetscan name fields, object groups and arrays. Naming a group or an array shows or hides all of its fields. A target that doesn’t exist, or a field inside an array, is skipped, and the rule still applies to its other targets.- A condition’s
fieldmust be a field: a condition on an object group or an array makes the rule invalid.