Skip to content
Start free

Conditional Logic

Open in ClaudeOpen in ChatGPT

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.

  1. Select a field in the template editor.
  2. Scroll down to the Conditional Logic section.
  3. Click + Add Condition.
  4. 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.

  • 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.
OperatorDescription
Is PresentThe field has any non-blank value
Is BlankThe field is empty
EqualsThe field’s value matches exactly
Does Not EqualThe field is blank, or has a different value
Is One OfThe field’s value matches one of the listed values
Greater, Greater or Equal, Less, Less or EqualNumeric comparisons (for Number fields)
In RangeThe 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.

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.

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.

  • 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 422 error.

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 the then branch of its conditional in the top-level allOf. 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 the then branch into the schema), and keeps additionalProperties: false working; any stale value for a hidden field is accepted (and ignored by DocSpring).
  • Conditionally required fields are listed in the then branch’s required array. Rule targets are never in the base required array, 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 base properties and its conditional only adds required.
  • 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-dependencies array describing its rules in a machine-readable format (including a requiredWhenMatched flag). The conditionals DocSpring generates are marked x-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
}
]
}

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, or require
  • match: all or any
  • operator: present, blank, equals, not_equals, in, gt, gte, lt, lte, or range (use value for the lower bound and range_max for 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 as 5, -1.5 or 1e3 (range needs at least one bound; a missing bound makes the range open-ended).
  • Field names use the same a/b/c path 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 without group are stored as given.
  • targets can 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 field must be a field: a condition on an object group or an array makes the rule invalid.