> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Naming a template's fields

> How much of a template you can address, renaming its fields once for every envelope after, and sending against the version you checked.

export const batchTemplateChangedCode = "template_changed";

export const createTemplateChangedCode = "template_changed";

export const renameSubjectUnknownCode = "value_subject_unknown";

export const renameNotWritableCode = "value_not_writable";

export const renameOwnerRemovedCode = "api_key_owner_removed";

export const renameTestKeyCode = "test_key_cannot_edit_templates";

export const namingRuleCode = "naming_rule_broken";

export const renameFieldUnknownCode = "field_unknown";

export const renameStaleCode = "template_changed";

export const renamePreconditionCode = "precondition_required";

export const coreSubjectKeys = "spouse, dependant_<n>, beneficiary_<n>, witness_<n>";

export const coreNamespaces = "person, employer, employment, residential_address, postal_address, bank";

export const keySegmentMax = "40";

export const labelMaxLength = "200";

export const dataKeyMaxLength = "100";

export const renameMaxQuestions = "200";

export const renameMaxFields = "500";

export const testKeyPrefix = "vsk_test_";

export const scopeTemplatesName = "templates:name";

export const templateReadScope = "templates:read";

A value reaches a box through the box's address, its `(subject, data_key)` pair. A template made
from a real form often arrives with boxes that have no `data_key`, or with keys derived from the
printed labels, such as `yes` or `date_birth`. This page is about fixing that once, on the
template, so that every envelope created from it afterwards is addressed the way your data is.

## How much of a template you can address

[`GET /api/v1/templates/{templateId}`](/api-reference/get-template) carries `coverage`, counted by
the same code as the line under the template's name in the editor, so the two always agree.

| Property | What it counts |
| - | - |
| `prefillable` | fields you may write a value into: every type except those the signer performs or the system stamps |
| `core` | prefillable fields whose key is in the core vocabulary, which is not published yet |
| `organisation` | prefillable fields whose key follows the naming grammar below |
| `legacy` | prefillable fields with any other key; it still works as an address, and is a name to replace |
| `unnamed` | prefillable fields with no key: nothing can be written into them |
| `questions` | tickbox questions |
| `unnamed_groups` | questions none of whose boxes has a key |
| `unnamed_options` | boxes with no key in a question where another box has one |
| `collisions` | fields sharing an address they cannot share: two checkboxes at one address, which any value would tick together, or two fields of different types |

Two fields of the same other type at one address are not a collision: that is one datum printed
twice, such as an ID number on the application and again on the declaration, and one value fills
both.

## Reading a template only when it has changed

Every read of a template answers with an `ETag`: the hash of the whole body, `context`, `coverage`
and `warnings` included, so it changes whenever anything in the body does. Send it back as
`If-None-Match` and, while nothing has changed, the answer has no body. It still counts as a
request against your rate limit. Test and live keys holding
<code>{templateReadScope}</code> both get it.

## Renaming fields

[`PATCH /api/v1/templates/{templateId}/fields`](/api-reference/rename-template-fields) sets a
field's `data_key`, `label` and `subject`, and a question's label.
[`PATCH /api/v1/templates/{templateId}/fields/{fieldId}`](/api-reference/rename-template-field) does
the same for one field.

```json theme={null}
{
  "fields": [
    { "id": "6c1e…", "data_key": "member.surname", "label": "Surname" },
    { "id": "9a40…", "data_key": "member.id_number", "subject": "spouse" },
    { "id": "b2d7…", "data_key": null }
  ],
  "questions": [{ "id": "4b0f…", "label": "Gender" }]
}
```

* **Names only.** Nothing else about a field can change here: not where it is, its type, who fills
  it, its options, its rules or its conditions. Any other property is refused. A name is not inert,
  though: a field's `data_key` decides which value an envelope can be created with in that box, and
  its `subject` whether the box is shown when that person is not on the envelope. That holds for a
  required field too: moving one to a subject who may be absent makes it optional whenever they
  are, exactly as the same change in the editor does.
* **A dedicated scope.** The key must name <code>{scopeTemplatesName}</code>. A full-access key does
  not hold it; choose it by name when you create the key.
* **Live keys only.** A template has no environment: the same template serves test and live sends.
  A rename made with a <code>{testKeyPrefix}</code> key would change what live envelopes contain,
  so it is refused with <code>{renameTestKeyCode}</code>. A key whose creator has left your
  organisation is refused with <code>{renameOwnerRemovedCode}</code>.
* **Against the version you read.** Send the template's `ETag` as `If-Match`. Without it, or with
  `*`, the answer is <code>{renamePreconditionCode}</code>. If the template has changed since, the
  answer is <code>{renameStaleCode}</code> with the current `ETag`, and nothing is renamed: read
  the template again and look at what changed before you retry. A retry of a rename that succeeded,
  whose answer you lost, is answered as a success: every name it asks for is already there.
* **All or nothing.** At most {renameMaxFields} fields and {renameMaxQuestions} questions in one
  request. Every change applies, or none does.
* **Only envelopes created afterwards** use the new names. An envelope already created, sent or not,
  keeps the names it was created with, and the values it holds stay where they were.
* **Recorded.** Every change is kept in the template's naming record with the key that made it, and
  each request that changes a name appears in your organisation's activity. A rename in the editor
  is recorded the same way.

### What a name may be

A key you set is at most {dataKeyMaxLength} characters and follows the naming grammar:
`namespace.attribute` or `namespace.entity.attribute`, each segment snake\_case starting with a
letter and at most {keySegmentMax} characters, such as `medical_aid.plan` or `funeral.cover.amount`.

* The namespaces <code>{coreNamespaces}</code> belong to the core vocabulary, a shared list of keys
  that is not published yet. No key in them can be set until it is.
* A namespace may not be a subject key, either one the template declares or one of the standard
  ones, <code>{coreSubjectKeys}</code>, where n counts from one. The subject is never part of the
  key: set `subject` instead.
* A key a field already has may be kept, whatever it says. `data_key: null` removes it.
* A box in a question takes no key or subject of its own; name it with `label`. Option values, and
  a question's own key, come with the core vocabulary.
* A rename may not make a collision, as `coverage` counts them. A collision the template already
  had does not stop you renaming other fields, which is how you fix it.
* A `label` is at most {labelMaxLength} characters, and not blank; `null` removes it. It may be
  changed on any field, a signature or a question's box included, as in the editor. A label is
  Vumasign's name for the box; it does not change the printed document, which is what decides what
  a tick or a signature means. A `subject`
  must be declared on the template.
* ⚠️ A `subject` never changes here on a field nobody may prefill: a signature, initials, an
  attachment or a field the product stamps. On those fields the subject decides whether somebody
  must sign or complete them, and a key must not be able to change that unseen. The request is
  refused with <code>{renameNotWritableCode}</code>. This is deliberately stricter than the editor,
  which allows it.

A rule about what a name says is <code>{namingRuleCode}</code>, and the message names the rule and
the fields. A key or a new subject on a field nobody may prefill is <code>{renameNotWritableCode}</code>, a subject
the template does not declare is <code>{renameSubjectUnknownCode}</code>, and an id that is not
one of the template's is <code>{renameFieldUnknownCode}</code>.

## Sending against the template you checked

[`POST /api/v1/envelopes`](/api-reference/create-envelope) and
[`POST /api/v1/envelopes/batches`](/api-reference/create-envelope-batch) take an optional
`template_etag`: the `ETag` you read, or the `template_etag` that
[`validate-values`](/api-reference/validate-template-values) answers with. If the template has
changed since, the create is refused with <code>{createTemplateChangedCode}</code> (for a batch,
<code>{batchTemplateChangedCode}</code>), and nothing is created.

Send it on every envelope. A value for a key that no longer exists is refused loudly. But if two
addresses were swapped, say the member's ID number and the spouse's, a value would land in the
wrong box and nothing would say so. `template_etag` is what catches that.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.