Use Predefined Fields

Predefined fields let you give embedded template editor users a controlled list of field names and data types. This is useful when your application already knows the data model that will be submitted later.

Template Configuration

Set predefined_fields when creating or updating a template through the API:

{
"template": {
  "predefined_fields": [
    {
      "name": "customer/name",
      "type": "string",
      "required_in_template": true
    },
    {
      "name": "customer/email",
      "type": "string",
      "required_in_template": true,
      "field_required": true
    },
    {
      "name": "agreement/signed_at",
      "type": "date",
      "required_in_template": false,
      "field_required": false
    }
  ]
}
}

When predefined fields are enabled in the template editor, users can assign fields from the predefined list instead of typing arbitrary field names.

Use required_in_template when a predefined field must be added to the template at least once. This controls the missing/present indicator in the predefined field list and whether the “Done” button is enabled in embedded template editors (via the disableDoneButtonIfPredefinedFieldsMissing option.) The Done button also remains disabled while template changes are pending, while a save is in progress, or while a save error is present.

Use field_required to set the template field’s own required value when a user adds or assigns that predefined field. This controls whether submission data must include a value for the field. If field_required is omitted, it defaults to true.

If you are using the embedded template editor, you can show or hide the Required checkbox in the fields options by setting showFieldRequired. Set this to true if you want your users to be able to control whether fields are required or optional. (The default is the field_required that you can set for each predefined field.)

API Reference: Update a Template Set predefined_fields and other template attributes via the API

Field Names

Use slash-separated names for nested JSON data:

{
"customer": {
  "name": "Ada Lovelace",
  "email": "[email protected]"
},
"agreement": {
  "signed_at": "2026-06-22"
}
}

For repeated fields, use array-style names such as signers/0/name and signers/1/name.

Embedded Editor

Predefined fields are enabled by default. You can disable them for a specific embed:

DocSpring.createTemplateEditor('#template-editor', {
templateId: 'tpl_123',
token: 'EMBED_EDIT_TOKEN',
inline: true,
features: {
  showPredefinedFields: false
}
})

Customize the Embedded Template Editor Learn about all embedded editor feature switches