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), index_bits and filename_field (for a file field, below). A collection may set a parent to nest it under another.

File fields

A field declared type: file holds a file, stored and retrieved with custodian file. A file field must be client_encrypted.

A file field may set filename_field to name a sibling field in the same collection that holds the file's name. custodian file get writes the file under the name it finds there:

collections:
  policyholders:
    fields:
      passport_scan:
        type: file
        sensitivity: client_encrypted
        filename_field: passport_scan_name
      passport_scan_name:
        type: string
        sensitivity: client_encrypted

The command line checks only that filename_field is a string. Any other value is refused before anything is sent:

error: Field "passport_scan"'s filename_field must be a field name.

Whether the string names a real field is checked by the server when you apply. It checks that the named field is in the same collection, is declared string and is not itself a file, and refuses the apply if not. Those refusals, and the other rules for file fields, are listed under file fields in the schema API.

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

Setting or changing a file field's filename_field appears as its own line. It is not destructive: the stored file stays readable, and only the name it is written under changes.

  ~ field policyholders.passport_scan filename field: null → "passport_scan_name"

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.

Applying an unchanged file

apply always sends the file to the server, even when the preview shows no changes. Whether an unchanged file needs applying is the server's decision, and the server may advance the version by one with no changes. The output says what is happening, then reports what the server did:

no changes to send (at schema version 3) — asking the server to re-apply.
  applied · schema version 4
Updated schema.yaml: version is now 4.

The one-time step after upgrading to v0.5.0

From v0.5.0, the way a schema's digest is computed has changed, so the digest of every schema file changes, even one you have not edited. Until you re-apply it, the server does not recognise your unchanged file as the schema it already holds. Re-apply each vault's schema once, signed in to that vault:

custodian schema apply schema.yaml

If you are signed in to more than one vault, add --vault <slug> to name the one the file belongs to (see selecting a deployment and vault).

Run it on the file as it was last applied. If the file holds edits you have not applied yet, this run applies them too, and an additive change goes through without a question. Run custodian schema diff schema.yaml first: if it lists any changes, the file is not the one last applied.

The apply advances the schema version with no changes. Stored values, tokens and blind indexes are unaffected. If you skip the step, nothing stops working: the version advance happens instead the next time you apply the file. See the v0.5.0 changelog entry.

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

A file field that names a filename field shows it among its attributes:

collection policyholders
  passport_scan       file, client_encrypted, filename field: passport_scan_name
  passport_scan_name  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.

schema apply --json reports an applied change as one object. Applying an unchanged file gives the same shape, with an empty changes list:

{"applied":true,"version":4,"wrote_version":true,"changes":[]}

schema diff --json includes the file's digest. From v0.5.0 the digest of every schema file is different from the one earlier releases computed, even for an unchanged file.