Skip to content

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/document-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 label, and a value type (string, date, number, or boolean). 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. 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.

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.

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. 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.

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 catalogue 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.