Field compliance directives

A compliance directive declares how a field must be handled: at rest, on read, in logs, in exports and in indexes. It is a data-classification and protection control on your schema.

fields:
  - name: national_id
    type: string
    compliances: [pii]

That single tag is not a label. It applies a protection bundle.

Classify, and the defaults follow

Tagging a field with a classification, pii, phi, pci or gdpr, automatically applies:

Dimension	Default	Why
At rest	`encrypted`	Ciphertext in the column
On read	`mask`	Output shows a masked representation
Logs and copies	`nolog`	The value never enters a log line, an audit row or an event payload
Exports	`noexport`	Never appears in a schema or data export
Indexes	`noindex`	Only when encrypted or tokenized. A plaintext index over ciphertext would defeat the encryption

The reasoning is worth stating plainly: a schema author should not be able to leave regulated data unprotected by forgetting a directive. Classification is the thing people remember; the bundle is what they forget.

Overriding a default

Each dimension is applied only if you have not already expressed a conflicting directive for that dimension. The dimensions are independent, so overriding one leaves the rest in place.

Dimension	Directives (mutually exclusive)
On read	`mask` · `redact` · `hidden`
At rest	`encrypted` · `tokenize` · `hash`

compliances: [pii, redact]      # redacted on read, still encrypted, nolog, noexport
compliances: [pii, tokenize]    # tokenized at rest, still masked on read

nolog and noexport are additive. They never conflict with anything, so for a classified field they always apply. You cannot accidentally turn them off by adding another directive.

The directives

On read

Directive	Effect
`mask`	Output shows a masked representation
`redact`	Output shows a redaction marker
`hidden`	The field is omitted from output entirely

At rest

Directive	Effect
`encrypted`	Ciphertext in the column
`tokenize`	Stored as a token; the value lives elsewhere
`hash`	One-way. The original is not recoverable

In copies

An audit row (history: { strategy: typeaudit }) and an event payload (events:, the outbox, webhooks) are copies of a row’s values. A read is shaped for the principal reading it; a copy has no principal, so it takes the most restrictive shape the field allows:

Directive	In `<entity>_audit`	In an event payload
`hidden`	No row for the field	Field absent
`nolog`, `redact`	`[REDACTED]` on both sides; the row still says the field changed	`[REDACTED]`
`mask`	The masked value	The masked value
`encrypted`, `tokenize`, `hash`	The stored form (ciphertext, token, hash)	The stored form

Whether a field changed is decided on the real values before the copy is shaped, so two values that mask alike still produce an audit row. An embeddable’s sub-fields follow the same rules inside the document.

Always additive

Directive	Effect
`nolog`	Never enters a log line, an audit row or an event payload
`noexport`	Never appears in a schema or data export
`noindex`	No index is emitted over the column

Classifications

Directive	Means
`pii`	Personally identifiable information
`phi`	Protected health information
`pci`	Payment card data
`gdpr`	In scope for GDPR

Other

Directive	Effect
`searchable`	See below
`retention`	Marks the field for the retention runner. Parsed here, enforced there

Keeping a classified field searchable

Encryption and querying pull in opposite directions, an encrypted email column cannot be looked up by value.

searchable is the escape hatch: it suppresses default encryption for a classified field that must remain queryable.

- name: email
  type: string
  compliances: [pii, searchable]

Mask, nolog and noexport still apply. The value is still masked on read, still kept out of logs and exports, only the at-rest encryption is dropped, and only because you asked.

One resolution point

Everything that needs a field’s posture goes through the same resolution: read masking, at-rest encryption on both write and read, the schema exporters, and the index emitter during migration.

That matters because it is the only way the policy stays coherent. If masking resolved compliances differently from export, a field could be masked in an API response and plain in a CSV, which is exactly the failure this design exists to prevent.

A deployment without keys

Default encryption is a no-op at runtime when no key provider is configured: the encrypting hook skips.

That keeps the policy from breaking a deployment that has not set up keys yet. It also means a classified field can be sitting in plaintext while the schema says encrypted, so verify key configuration before treating classification as protection.

Compliance versus transform

They are easy to confuse and do different jobs.

	Compliance	Transform
Governs	Who may see the value	What the value is
Applied	At read, write, export and index, per policy	On write, in declared order
`hash`	Protection policy. A bundle dimension	A function that rewrites the stored value
Reversible	`encrypted` and `tokenize` are	Only if the function is

A masked field still stores the real value. A mask_partial transform changes what is stored. Reach for the compliance when the requirement is about access, and the transform when it is about content.