Policy YAML reference

A Metatate policy is a single YAML (or JSON) document validated against the DataPolicy schema. Validation is strict: unknown fields are rejected at every level, with one escape hatch — an optional extensions map at each level for your own extension data. The YAML parser uses the safe default schema (no date coercion, no executable tags), and blank values in governance fields are hard errors, so a policy can never silently govern nothing.

Top-level structure

apiVersion: metatate.io/v1
kind: DataPolicy
metadata: { ... }
spec: { ... }
extensions: { ... } # optional

Field	Required	Value
apiVersion	yes	Must be exactly metatate.io/v1.
kind	yes	Must be exactly DataPolicy.
metadata	yes	Identity and business context.
spec	yes	Scope, classification, and rule sections.
extensions	no	Scenario mapping, display metadata, and free extension keys.

metadata

Field	Required	Value
name	yes	1–64 character lowercase slug (letters, digits, internal dashes).
version	yes	Semver MAJOR.MINOR.PATCH (prerelease and build metadata allowed).
description	no	What the policy does.
intent	no	The authoring intent behind the policy.
sourceType	no	Data provenance note (for example crm_sync); emits a lineage instruction.
businessContext	no	Object with optional purpose, domain, owner, steward; emits an advisory business-context instruction.
tags	no	Free-form string labels on the policy.

spec basics

Field	Required	Value
enforcementMode	yes	enforce, monitor, or advisory. In monitor and advisory modes, enforceable rules are served as require_review instead of their active decision.
priority	yes	Integer 0–999. 800–999 ranks critical, 500–799 high, 300–499 medium, 101–299 low; 100 and below falls back to the classification sensitivity.
selector	yes	Target scope (below).
classification	yes	sensitivity (public, internal, confidential, restricted), category (must start with pii, phi, pci, financial, intellectual_property, operational, or public — exact, or extended like pii.contact), optional subcategory.

spec.selector

The selector names what the policy governs, across seven first-class target dimensions. At least one dimension must be non-empty — an unscoped policy is rejected. Matching is exact against normalized catalog identifiers; wildcard characters (*, ?, [, ]) are rejected because they would silently match nothing.

Dimension	Value	Notes
databases, schemas	Identifier names	Hierarchical filters over the other dimensions.
tables	Table names	Table-level targets.
columns	Column names	Column-level targets within the table universe (or estate-wide if no tables are named).
tags	Tag names	Each also emits a governance-tag instruction.
collections	Collection ids	Targets a named group of tables by id; at most 64 entries, each up to 256 characters.
taxonomyTypes	Classification type keys	Targets every column classified with the type (for example pii.contact.email); same bounds as collections.

Composition: explicitly named tables plus the active member tables of listed collections form the table universe, filtered by databases and schemas. taxonomyTypes refine to column level — intersected with the table universe when one exists, otherwise matching classified columns estate-wide. When both columns and taxonomyTypes are present, the column targets are their union. Collection and taxonomy targets are resolved at deployment time against the current catalog, so classify-once governance follows your estate as it grows.

Rule sections

All rule sections are optional; each present section must carry real content.

spec.accessControl — masking (type starting with none, partial, full, hash, tokenize, encrypt, redact, dynamic, conditional, or custom; optional config object and exemptRoles; type none emits nothing), plus allowedRoles and deniedRoles lists that become per-role allow/deny instructions.

spec.rowFilter — optional description, plus required non-empty rules. Each rule has a required non-blank expression (the row predicate), optional roles (must name at least one role when present; omit it for a table-wide predicate), and optional description. Serves as a conditional decision carrying the obligation.

spec.usage — permittedUses and/or prohibitedUses, open-vocabulary use names; at least one list must be non-empty. Permitted uses serve allow, prohibited uses serve deny.

spec.aiGovernance — allowTraining, allowInference (booleans that serve allow/deny for AI training and inference), requiresAnonymization (serves conditional), and free-form restrictions.

spec.retention — optional period, trigger, action free strings; serves retain.

spec.compliance — required non-empty regulations list of named regimes (open vocabulary, for example GDPR); served as compliance context.

spec.transferGovernance — defaultEffect (allow, deny, conditional) and rules, each with optional effect, operations, destinationSystems, destinationJurisdictions, consumerJurisdictions, requiresApproval, requiresAnonymization, requiredRole. A satisfiable approval or anonymization path serves conditional; an outright deny serves deny. Extra keys pass through.

extensions

Field	Purpose
scenarioMap	Maps a stable instruction key to { scenarioKey, source }, overriding an instruction's default canonical scenario. scenarioKey must be canonical (see Scenarios); source is defaulted, ai_suggested, or user_confirmed.
scopeRefs	Structured display/provenance references for tables, collections, taxonomy types, and roles. Authoring metadata only — spec.selector stays authoritative.
instructionDisplay	Display-only title/description overrides per instruction key. Never deployable.
any other key	Unknown extension keys pass through unchanged (for example displayName).

Worked example

This is a complete, real policy from the AcmeCloud sample estate, exactly as the demo workspace authors and publishes it:

# AcmeCloud estate spec — customer data use guardrails.
# Real Metatate Cloud policy DSL: this exact document is what the demo
# workspace authors, approves, and publishes; the served instruction rows
# are derived from it by the real governance engine.
apiVersion: metatate.io/v1
kind: DataPolicy
metadata:
  name: acme-customer-use
  version: 1.0.0
  sourceType: crm_sync
  description: >-
    Customer data supports analytics, reporting, and support workflows;
    marketing, advertising, personalization, and model training are
    prohibited. AI training is blocked and inference requires anonymization.
  tags: [pii, privacy_sensitive, ai_training_blocked]
  businessContext:
    domain: Customer Data
    owner: Revenue Operations
    steward: privacy-review@example.com
    purpose: >-
      Customer master data used for approved reporting, analytics, support,
      and controlled operational exports.
spec:
  enforcementMode: enforce
  priority: 550
  selector:
    databases: [acmecloud_demo]
    schemas: [public]
    tables: [customers, support_tickets, product_usage_events]
    tags: [privacy_sensitive]
  classification:
    sensitivity: confidential
    category: pii
  usage:
    permittedUses: [analytics, reporting, support]
    prohibitedUses: [marketing, advertising, personalization, ml_training]
  aiGovernance:
    allowTraining: false
    allowInference: true
    requiresAnonymization: true
extensions:
  displayName: AcmeCloud customer use guardrails
  scenarioMap:
    "usage_guidance:spec.usage.prohibitedUses:prohibited":
      scenarioKey: purpose.prohibited_use
      source: user_confirmed

Walking through it: the selector scopes three tables in acmecloud_demo.public plus the privacy_sensitive tag, at priority 550 (high) in enforce mode. The usage section produces an allow instruction for analytics, reporting, and support, and a deny instruction for the prohibited uses — which the scenarioMap pins to the canonical purpose.prohibited_use scenario as a user-confirmed choice. The aiGovernance section splits into three instructions: AI training denied, inference allowed, and a conditional anonymization obligation. Classification, sourceType, and businessContext serve as context alongside the decisions.

From YAML to deployable instructions

Saving a valid document creates a canonical policy version; approving it makes it ready. Metatate then deterministically extracts the deployable instructions above — each with a scenario, decision, priority, enforcement mode, reason, and provenance — and a deployment publication makes them live. Ready is not live: nothing here answers a query until it is published. See Policies in the app and the governance model.