Item kinds and records¶
A kind is a controlled-vocabulary entry that categorizes what a
vault item is. Kinds are configuration entities (stable machine names
across environments), managed at Configuration -> Personal Data
Vault -> Item kinds (/admin/config/pdv/item-kinds).
Consumers refer to kinds by machine name (for example a workflow asks
for the user's id_card), so the vocabulary is structural, not
user-generated.
Two types of kind¶
Each kind has a type:
- Document - the item is an uploaded file (the default).
- Record - the item is a set of structured fields stored together as one encrypted unit (for example a civil-status record holding full name, birth date, birth place, and nationality).
A record kind declares its fields, each with a machine name (a lowercase
letter, then lowercase letters, digits and underscores), a label, and a value
type (string, date, number, boolean, or choice). Edit them on the
kind form, one per line:
full_name | Full name | string
birth_date | Birth date | date
nationality | Nationality | string
A record is stored as the encrypted JSON of its field values, using the exact same encryption, grants, and erasure as a document. It holds only the kind's fields, each of its type: text of at most 255 characters, a date as YYYY-MM-DD, a number, yes/no, or one of a choice field's values. A form's number text and checkbox are stored as their number and yes/no; a value that fits no field, from a consumer or a form, is refused rather than stored. Sharing is always whole-record: a consumer granted a record receives all of its fields. To share a single value on its own, define a record kind with one field.
Choice fields¶
A choice field takes one value from a fixed list: a family situation, a
schooling level, a family link. List its values after its type, each as
value=Label, separated by semicolons:
family | Family | choice | single=Single; married=Married; civil=Civil union
schooling | Schooling | choice | none=None; primary=Primary; secondary=Secondary
- The value (
married) is what the record stores and what a consumer sends and receives. It is text of at most 255 characters, without=,;or|, which the line uses to separate its parts. A value written without a label is its own label (yes; no). - The label (
Married) is what the owner sees: the record form shows a select of the labels, with an empty choice to clear the field, and the record page shows the chosen label. A label holds neither;nor|. - Any other value is refused, from the owner's form or a consumer alike. The
refusal lists the values the field takes, so a consumer learns what to send
(
invalid_payloadover the cross-site API). Empty text clears the field, asnulldoes: it is what an empty select sends.
Choose the values so that a form can send them as they are. A Webform select
or radios element whose option keys are the field's values prefills from the
record and writes back without any conversion: for example a select with the
options single, married and civil, labelled in the form's own language.
Unique kinds¶
A kind can be marked unique per person: the owner may hold only one item of that kind (an identity card, a passport, a civil-status record). Adding another never happens silently:
- On upload, a "Replace existing document" checkbox appears for unique kinds; without it the upload is refused, and with it the previous item is cryptographically erased and replaced.
- A consumer-offered upload for a unique kind that already exists is not auto-stored even for a trusted consumer; it routes to the consent page so the owner confirms the replacement.
Tenant scope¶
On a multi-tenant site a kind is either shared (offered in every tenant, the default) or scoped to one tenant. A Tenant selector appears on the kind form once more than one tenant exists, and the Item kinds list gains a Tenant column. Single-tenant sites never see this: every kind is simply shared.
A kind in use¶
Once owners hold passports, the passport kind keeps what those items depend
on. Its form, a configuration import and code are all refused:
- Deleting it, while a vault item or a store request waiting for approval uses it. The item would name a kind that no longer exists, and a record would have no fields to show its values by.
- Changing its type, while it is in use the same way. A document read as a record does not open.
- Limiting it to a tenant that leaves some of its items outside, or while a store request of it waits for approval. Sharing it with every tenant is always allowed.
- Removing a record field, changing its type, or removing a value from a choice field, while it is in use. Its records would hold values the kind no longer accepts, and every update of them would be refused. The vault cannot see which values the records hold without opening every owner's records, so removing any value is refused, even one no record holds.
Its label, description, weight and uniqueness can still be edited, record fields added, relabelled or reordered, and choices added or relabelled.
Starter kinds¶
The module installs: identity card, passport, and driver's license (all unique documents); CV, diploma, tax form, and "other" (documents); and a civil-status record (unique). Adjust or replace these to fit your site.
Translating kinds¶
A kind's label and description are translatable, and so are its record
fields' labels and its choice labels. On a multilingual site, use the
Translate operation on the Item kinds list (or the Translate tab on a
kind) to add each language's wording - for example id_card becomes "Carte
d'identité" in French, and the choice married shows as "Marié(e)". A
choice's value stays the same in every language.
The vault is the single source of these translations. Everywhere a kind is named to a user - the owner's own forms and, over the cross-site API, remote consumer sites - the label is shown in the current user's language, resolved from this one place; a machine name is never shown. A remote consumer fetches the label catalog from the vault and caches it per language (see Client-server configuration).
French translations ship for the starter kinds out of the box; translate any kinds you add yourself.