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

Display names and titles

Set an optional display_name to show a friendly name throughout the template editor while keeping name as the field’s submission data key:

{
"name": "requiredInfo_name",
"display_name": "Defendant/Name",
"title": "Defendant Name",
"type": "string",
"required_in_template": false,
"field_required": false
}

This field appears as Name inside a Defendant folder in the field sidebars, and as Defendant/Name in the name dropdown and on the editor canvas. Its actual name remains requiredInfo_name, so submission data is still {"requiredInfo_name": "Jane Smith"}. Display folders do not create nested submission data.

The optional title populates the field’s Title setting when the field is added or assigned from the predefined list. Users can edit that title afterward. Changing the predefined title does not overwrite titles on fields already placed in the template.

If display_name is omitted or null, the editor uses name. If title is omitted or null, adding or assigning the predefined field does not supply a title. Existing configurations continue to work without these properties.

Each predefined field must have a string name that is not empty or composed only of whitespace. Valid names are stored exactly as supplied.

Display names must be non-empty strings and must not create ambiguous choices for different field names. This includes collisions with fields that use their original names, or a legacy array dropdown label. For example, Defendant/Name and Cosigner/Name are allowed, but two different data keys cannot both be displayed as Defendant/Name. The API returns a validation error when saving conflicting predefined fields. Multiple placements of the same field are allowed.

If the predefined list repeats the same exact name, every entry must have identical display_name and title values. Omitted and null values are equivalent. For example, person cannot be configured once as Defendant/Name and again as Cosigner/Name. Repeated entries with no presentation metadata or with identical metadata remain valid.

Array entries with explicit display names appear as separate Name dropdown choices. Without display names, array entries share a Name dropdown choice. The index selector lists only configured entries using one-based indices. Changing the index applies the selected entry’s title (when supplied), type, required state, and option list, just like selecting it from the Name dropdown.

Nested data and arrays

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