Form operations

6 operations named form.*. Every one runs in a batch through apply_ops, dry_run_ops, the CLI or the admin.

Updated
OperationWhat it doesPermissionConfirmation
form.listList the forms of the site with their fields and settings.site.readnone
form.readRead a form: its key, label, fields and settings.site.readnone
form.createCreate a form with its fields and settings.site.editnone
form.updatePatch the label, fields or settings of a form.site.editnone
form.deleteDelete a form and every submission it received.site.editdestructive
form.sendTestRender the notification a submission of the form sends, with sample values for its fields.site.editnone

form.list

List the forms of the site with their fields and settings. Forms are not versioned: a saved definition takes effect at once.

permission: site.readreads onlyclass: read

Example input

{}

Input

The input is a record; see the schema below.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output

FieldTypeRequiredNotes
formsarray of objectyes
forms[].idstring (uuid)yes
forms[].keystringyesAt most 40 characters.
forms[].labelstring | record of stringyes
forms[].fieldsarray of objectyes
forms[].settingsobjectyes
forms[].createdAtstring (date-time)yes
forms[].updatedAtstring (date-time)yes

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash form.list '{}' --dry-run

form.read

Read a form: its key, label, fields and settings. Forms are not versioned: a saved definition takes effect at once.

permission: site.readreads onlyclass: read

Example input

{
  "formId": "d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f8a"
}

Input

FieldTypeRequiredNotes
formIdstring (uuid)yes

Output

FieldTypeRequiredNotes
formobjectyes
form.idstring (uuid)yes
form.keystringyesAt most 40 characters.
form.labelstring | record of stringyes
form.fieldsarray of objectyes
form.settingsobjectyes
form.createdAtstring (date-time)yes
form.updatedAtstring (date-time)yes

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash form.read '{"formId":"d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f8a"}' --dry-run

form.create

Create a form with its fields and settings. The key is unique on the site and never changes; a ds.form node names the form by its id. Forms are not versioned: a saved definition takes effect at once.

permission: site.editwrites: formsclass: transactionundo: yes

Example input

{
  "form": {
    "key": "contact",
    "label": {
      "it": "Contatti",
      "en": "Contact"
    },
    "fields": [
      {
        "key": "name",
        "type": "text",
        "label": {
          "it": "Nome",
          "en": "Name"
        },
        "required": true,
        "maxLength": 120
      },
      {
        "key": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "key": "topic",
        "type": "select",
        "label": {
          "it": "Argomento",
          "en": "Topic"
        },
        "options": [
          {
            "value": "visit",
            "label": {
              "it": "Visita",
              "en": "Visit"
            }
          },
          {
            "value": "press",
            "label": {
              "it": "Stampa",
              "en": "Press"
            }
          }
        ]
      },
      {
        "key": "message",
        "type": "textarea",
        "label": {
          "it": "Messaggio",
          "en": "Message"
        },
        "required": true,
        "maxLength": 2000
      }
    ],
    "settings": {
      "recipients": [
        "info@example.com"
      ],
      "senderName": "Sito web",
      "replyToField": "email",
      "consent": true
    }
  }
}

Input

FieldTypeRequiredNotes
formobjectyes
form.keystringyesAt most 40 characters.
form.labelstring | record of stringyes
form.fieldsarray of objectyesAt least 1 item. At most 40 items.
form.settingsobjectnoDefault {}.
{
  "type": "object",
  "properties": {
    "form": {
      "type": "object",
      "properties": {
        "key": {
          "$ref": "#/$defs/__schema0"
        },
        "label": {
          "$ref": "#/$defs/__schema1"
        },
        "fields": {
          "$ref": "#/$defs/__schema4"
        },
        "settings": {
          "$ref": "#/$defs/__schema17"
        }
      },
      "required": [
        "key",
        "label",
        "fields"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "form"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "string",
      "maxLength": 40,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "__schema1": {
      "anyOf": [
        {
          "$ref": "#/$defs/__schema2"
        },
        {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/__schema3"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema2"
          }
        }
      ]
    },
    "__schema2": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "__schema3": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\\d{3}))?$"
    },
    "__schema4": {
      "minItems": 1,
      "maxItems": 40,
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema5"
      }
    },
    "__schema5": {
      "type": "object",
      "properties": {
        "key": {
          "$ref": "#/$defs/__schema6"
        },
        "type": {
          "$ref": "#/$defs/__schema7"
        },
        "label": {
          "$ref": "#/$defs/__schema1"
        },
        "help": {
          "$ref": "#/$defs/__schema8"
        },
        "placeholder": {
          "$ref": "#/$defs/__schema10"
        },
        "required": {
          "$ref": "#/$defs/__schema11"
        },
        "maxLength": {
          "$ref": "#/$defs/__schema12"
        },
        "showCount": {
          "$ref": "#/$defs/__schema13"
        },
        "pattern": {
          "$ref": "#/$defs/__schema14"
        },
        "options": {
          "$ref": "#/$defs/__schema15"
        }
      },
      "required": [
        "key",
        "type",
        "label"
      ],
      "additionalProperties": false
    },
    "__schema6": {
      "type": "string",
      "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$"
    },
    "__schema7": {
      "type": "string",
      "enum": [
        "text",
        "email",
        "tel",
        "textarea",
        "select",
        "checkbox",
        "date"
      ]
    },
    "__schema8": {
      "anyOf": [
        {
          "$ref": "#/$defs/__schema9"
        },
        {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/__schema3"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema9"
          }
        }
      ]
    },
    "__schema9": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "__schema10": {
      "$ref": "#/$defs/__schema1"
    },
    "__schema11": {
      "default": false,
      "type": "boolean"
    },
    "__schema12": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    },
    "__schema13": {
      "type": "boolean"
    },
    "__schema14": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "__schema15": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema16"
      }
    },
    "__schema16": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "maxLength": 40,
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
        },
        "label": {
          "$ref": "#/$defs/__schema1"
        }
      },
      "required": [
        "value",
        "label"
      ],
      "additionalProperties": false
    },
    "__schema17": {
      "default": {},
      "type": "object",
      "properties": {
        "recipients": {
          "default": [],
          "maxItems": 10,
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema18"
          }
        },
        "senderName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "replyToField": {
          "$ref": "#/$defs/__schema6"
        },
        "consent": {
          "default": false,
          "type": "boolean"
        },
        "honeypot": {
          "default": true,
          "type": "boolean"
        },
        "minFillMs": {
          "default": 2000,
          "type": "integer",
          "minimum": 0,
          "maximum": 60000
        },
        "open": {
          "default": true,
          "type": "boolean"
        },
        "action": {
          "default": {
            "kind": "inbox"
          },
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "inbox"
                }
              },
              "required": [
                "kind"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "accessRequest"
                },
                "fields": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "$ref": "#/$defs/__schema6"
                    },
                    "email": {
                      "$ref": "#/$defs/__schema6"
                    },
                    "studio": {
                      "$ref": "#/$defs/__schema6"
                    },
                    "website": {
                      "$ref": "#/$defs/__schema6"
                    },
                    "message": {
                      "$ref": "#/$defs/__schema6"
                    }
                  },
                  "required": [
                    "name",
                    "email"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "kind",
                "fields"
              ],
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "__schema18": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  }
}

Output

FieldTypeRequiredNotes
formobjectyes
form.idstring (uuid)yes
form.keystringyesAt most 40 characters.
form.labelstring | record of stringyes
form.fieldsarray of objectyes
form.settingsobjectyes
form.createdAtstring (date-time)yes
form.updatedAtstring (date-time)yes

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash form.create '{"form":{"key":"contact","label":{"it":"Contatti","en":"Contact"},"fields":[{"key":"name","type":"text","label":{"it":"Nome","en":"Name"},"required":true,"maxLength":120},{"key":"email","type":"email","label":"Email","required":true},{"key":"topic","type":"select","label":{"it":"Argomento","en":"Topic"},"options":[{"value":"visit","label":{"it":"Visita","en":"Visit"}},{"value":"press","label":{"it":"Stampa","en":"Press"}}]},{"key":"message","type":"textarea","label":{"it":"Messaggio","en":"Message"},"required":true,"maxLength":2000}],"settings":{"recipients":["info@example.com"],"senderName":"Sito web","replyToField":"email","consent":true}}}' --dry-run

form.update

Patch the label, fields or settings of a form. The change is live at once: the public form follows without a publish, and stored submissions keep the values they were sent with. Forms are not versioned: a saved definition takes effect at once.

permission: site.editwrites: form:{formId}class: transactionundo: yes

Example input

{
  "formId": "d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f8a",
  "patch": {
    "settings": {
      "recipients": [
        "info@example.com",
        "press@example.com"
      ],
      "senderName": "Sito web",
      "replyToField": "email",
      "consent": true
    }
  }
}

Input

FieldTypeRequiredNotes
formIdstring (uuid)yes
patchobjectyes
patch.labelstring | record of stringno
patch.fieldsarray of objectnoAt least 1 item. At most 40 items.
patch.settingsobjectno
{
  "type": "object",
  "properties": {
    "formId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "patch": {
      "type": "object",
      "properties": {
        "label": {
          "$ref": "#/$defs/__schema0"
        },
        "fields": {
          "minItems": 1,
          "maxItems": 40,
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema3"
          }
        },
        "settings": {
          "type": "object",
          "properties": {
            "recipients": {
              "default": [],
              "maxItems": 10,
              "type": "array",
              "items": {
                "$ref": "#/$defs/__schema15"
              }
            },
            "senderName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            },
            "replyToField": {
              "$ref": "#/$defs/__schema4"
            },
            "consent": {
              "default": false,
              "type": "boolean"
            },
            "honeypot": {
              "default": true,
              "type": "boolean"
            },
            "minFillMs": {
              "default": 2000,
              "type": "integer",
              "minimum": 0,
              "maximum": 60000
            },
            "open": {
              "default": true,
              "type": "boolean"
            },
            "action": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "const": "inbox"
                    }
                  },
                  "required": [
                    "kind"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "const": "accessRequest"
                    },
                    "fields": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "$ref": "#/$defs/__schema4"
                        },
                        "email": {
                          "$ref": "#/$defs/__schema4"
                        },
                        "studio": {
                          "$ref": "#/$defs/__schema4"
                        },
                        "website": {
                          "$ref": "#/$defs/__schema4"
                        },
                        "message": {
                          "$ref": "#/$defs/__schema4"
                        }
                      },
                      "required": [
                        "name",
                        "email"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "kind",
                    "fields"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "formId",
    "patch"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "$ref": "#/$defs/__schema1"
        },
        {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/__schema2"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema1"
          }
        }
      ]
    },
    "__schema1": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "__schema2": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\\d{3}))?$"
    },
    "__schema3": {
      "type": "object",
      "properties": {
        "key": {
          "$ref": "#/$defs/__schema4"
        },
        "type": {
          "$ref": "#/$defs/__schema5"
        },
        "label": {
          "$ref": "#/$defs/__schema0"
        },
        "help": {
          "$ref": "#/$defs/__schema6"
        },
        "placeholder": {
          "$ref": "#/$defs/__schema8"
        },
        "required": {
          "$ref": "#/$defs/__schema9"
        },
        "maxLength": {
          "$ref": "#/$defs/__schema10"
        },
        "showCount": {
          "$ref": "#/$defs/__schema11"
        },
        "pattern": {
          "$ref": "#/$defs/__schema12"
        },
        "options": {
          "$ref": "#/$defs/__schema13"
        }
      },
      "required": [
        "key",
        "type",
        "label"
      ],
      "additionalProperties": false
    },
    "__schema4": {
      "type": "string",
      "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$"
    },
    "__schema5": {
      "type": "string",
      "enum": [
        "text",
        "email",
        "tel",
        "textarea",
        "select",
        "checkbox",
        "date"
      ]
    },
    "__schema6": {
      "anyOf": [
        {
          "$ref": "#/$defs/__schema7"
        },
        {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/__schema2"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema7"
          }
        }
      ]
    },
    "__schema7": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "__schema8": {
      "$ref": "#/$defs/__schema0"
    },
    "__schema9": {
      "default": false,
      "type": "boolean"
    },
    "__schema10": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    },
    "__schema11": {
      "type": "boolean"
    },
    "__schema12": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "__schema13": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema14"
      }
    },
    "__schema14": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "maxLength": 40,
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
        },
        "label": {
          "$ref": "#/$defs/__schema0"
        }
      },
      "required": [
        "value",
        "label"
      ],
      "additionalProperties": false
    },
    "__schema15": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  }
}

Output

FieldTypeRequiredNotes
formobjectyes
form.idstring (uuid)yes
form.keystringyesAt most 40 characters.
form.labelstring | record of stringyes
form.fieldsarray of objectyes
form.settingsobjectyes
form.createdAtstring (date-time)yes
form.updatedAtstring (date-time)yes

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash form.update '{"formId":"d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f8a","patch":{"settings":{"recipients":["info@example.com","press@example.com"],"senderName":"Sito web","replyToField":"email","consent":true}}}' --dry-run

form.delete

Delete a form and every submission it received. A ds.form node that names it then draws its error state. Forms are not versioned: a saved definition takes effect at once.

permission: site.editwrites: forms, form:{formId}, submissions:{formId}class: transactionconfirm: destructiveundo: yes

Example input

{
  "formId": "d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f8a"
}

Input

FieldTypeRequiredNotes
formIdstring (uuid)yes

Output

FieldTypeRequiredNotes
successtrueyes

Needs confirmed: ["destructive"] on the batch, which the single-operation CLI form does not set: put it in a batch file and run yarn splash apply <file> --dry-run.

form.sendTest

Render the notification a submission of the form sends, with sample values for its fields. With dryRun (the default) the message is answered unsent; without it, it is sent to the form's recipients through the platform mail transport. Run it alone in a batch.

permission: site.editreads onlyclass: external

Example input

{
  "formId": "d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f8a",
  "dryRun": true
}

Input

FieldTypeRequiredNotes
formIdstring (uuid)yes
dryRunbooleannoDefault true.

Output

FieldTypeRequiredNotes
formIdstring (uuid)yes
dryRunbooleanyes
messageobjectyes
message.toarray of string (email)yesAt least 1 item.
message.fromNamestringno
message.replyTostring (email)no
message.subjectstringyesAt least 1 character.
message.textstringyes
message.htmlstringno
messageIdstring | nullyes

A dry run refuses an external operation, so it has no dry-run line: run it alone in a batch.

Generated from the operation registry and the MCP tool catalogue (source b5ef75cb0fb8c322).

Something wrong on this page? Write to docs@librettocms.com.

Libretto docs

Colophon. These docs are a Libretto site: 68 pages in two languages, 20 guide pages imported from Markdown and 41 reference pages generated from the operation registry. Set in Softcore, with code in IBM Plex Mono. Its outline:

/ Libretto docs /start Get started /start/request-access Request access /start/workspace Your workspace /start/first-site Your first site /start/invite-a-client Invite a client /start/connect-claude Connect Claude to Libretto /build Build /build/first-page Build a page /build/layers-and-canvas Layers and canvas /build/site-components Site components /design-system Design system /design-system/tokens Colours, space and themes /design-system/components Components and variants /design-system/fonts Typography and fonts /motion Motion /motion/scenes Scenes and recipes /motion/image-sequences Image sequences /motion/reduced-motion Reduced motion /publish Publish /publish/languages Site languages /publish/versions Publish and versions /publish/members-and-forms Members and forms /publish/domains Domains /handover Hand a site to a client /glossary Glossary /agents Agents and API /agents/mcp MCP server /agents/cli CLI /agents/batches Batches /agents/errors Errors and findings /agents/operations Operations /search Search