Policy naming

This page is generated from the PhiSQL spec artifacts for v1.0. Do not edit it by hand; change the artifact and rebuild.

The Phileas JSON policy schema has no top-level name field; policy identity comes from the filename. (A policy carries its description in metadata.description, but that is descriptive text, not identity.) These rules bridge that convention with PhiSQL's optional POLICY declaration.

Policy name

The policy name is the file basename (with the .phisql or .json extension stripped). This matches the existing convention in philterd/pii-redaction-policies and how Phileas resolves policies by name today.

The POLICY declaration

The POLICY declaration inside a PhiSQL document is optional. A PhiSQL file containing only REDACT / DEIDENTIFY / IGNORE statements is well-formed and compiles successfully.

Consistency rule

When the filename is known and a POLICY name is declared, the declared name must match the file basename after normalization (hyphens and underscores are treated as equivalent). A mismatch is a compile error.

Catches the common bug where someone copies a .phisql file to a new name and forgets to update the POLICY declaration inside.

Compiling from a string

When PhiSQL is compiled from a string with no associated filename (e.g., embedded in a tool's UI, included in another configuration format), the POLICY declaration is the only source of the name. If absent, the policy name is null and the caller must provide one.

The DESCRIPTION clause

The DESCRIPTION '' clause, when present on a POLICY declaration, compiles to metadata.description in the policy JSON, so the description travels with the policy through export, import, and sharing. The compiler also returns the text on CompileResult, which is what callers that keep a description elsewhere (such as a sibling .md file) read. Before schema 1.3.0 the schema had no description field and CompileResult was the only destination.