custodian schema

The schema is what your vault stores: its collections, the fields in each, and how each field is protected. You write it as one YAML file and apply it. The server works out and applies the change, so the tool always shows you what the server would do, never a second guess of its own.

Be signed in to the vault first.

The schema file

A schema file names the vault, a version number, and its collections. Each collection has fields, and each field declares a type and a sensitivity:

vault: acme
version: 3
collections:
  policies:
    description: Insurance policies
    fields:
      policy_number:
        type: string
        sensitivity: plain
        searchable: true
      holder_tax_id:
        type: string
        sensitivity: client_encrypted

A field's sensitivity is one of four values: plain, masked, tokenised or client_encrypted. Other attributes a field may declare include searchable, required, unique, mask, values (for an enumerated field) and index_bits. A collection may set a parent to nest it under another.

custodian schema diff <file>

Previews what applying the file would change, writing nothing:

custodian schema diff schema.yaml

It lists the collections and fields added, removed or changed, and tells you whether the change is destructive:

  + collection notes (2 fields)
  + field policies.underwriter (string, plain)
  - field policies.legacy_ref (destructive — 12 records hold a value in it)
  1 destructive change — apply needs --allow-destructive

A change that alters a field's sensitivity cannot be applied at all, and diff says so:

  this apply would be REFUSED — a field's sensitivity cannot be changed in place

custodian schema apply <file>

Runs the same preview, shows it, then applies it. An additive change goes straight through. A destructive change — removing a field or collection, changing a type, turning off searchable, or making a field required — needs --allow-destructive, and even then you are asked to confirm:

custodian schema apply schema.yaml --allow-destructive

Without the flag, a destructive change is refused, naming what it would do:

error: This apply is destructive and --allow-destructive was not given. It would remove field policies.legacy_ref (12 records hold a value). Re-run with --allow-destructive to be asked to confirm.

The flag grants permission to be asked; it does not skip the asking. To answer the confirmation without a prompt, add the global --yes.

A change to a field's sensitivity is refused in full, because every stored value would have to be re-encrypted from an enrolled device and the server holds no key to do it:

error: The apply was refused in full and nothing was applied: the sensitivity of policies.holder_tax_id cannot be changed in place, in either direction. Every stored value would need re-encrypting from an enrolled device, and the server holds no key to do it. Migrate the field to a new one instead.

On success, apply writes the new version number back into your file so the next apply carries the right version. --no-write-version leaves the file untouched and prints the number to set by hand.

custodian schema show

Renders the applied schema, every attribute of every field:

custodian schema show

schema version 3

collection policies
  policy_number  string, plain, searchable
  holder_tax_id  string, client_encrypted

--collection <name> shows only one collection.

custodian schema history

Lists every schema version, newest first, with who applied it, when, and what changed:

custodian schema history

Machine-readable output

Every one of these commands accepts --json.