Naming Tagging Standards

Naming, Comment & Tagging Standards

Enterprise-wide standards for Databricks asset naming, SQL comments, and cost/governance tagging.

Essential Rules (Retain in Working Memory)

After reading this skill, retain these 5 rules and release the full content:

1. snake_case everywhere — all object names: tables, columns, functions, schemas
2. dim_/fact_ prefixes — Gold tables prefixed by entity type; Bronze/Silver by layer
3. Dual-purpose COMMENT pattern — [Definition]. Business: [context]. Technical: [details].
4. Mandatory tags — layer, domain, PII (via class.* governed tags) on every table; team, cost_center, environment on every workflow
5. Budget policy tag — all serverless resources must use approved budget policies

Naming Quick Test (5-Point Gate)

Before generating ANY DDL, YAML, or Asset Bundle resource, verify all 5:

1. Layer prefix? — bronze_, silver_, dim_, fact_, bridge_, agg_
2. snake_case? — No camelCase, PascalCase, SCREAMING_CASE, kebab-case, or spaces
3. Schema COMMENT? — Every schema has a COMMENT via COMMENT ON SCHEMA
4. Table/column COMMENTs? — Dual-purpose format on every table and column
5. PII governed tags? — Scanned column names for class.* tag candidates

If ANY answer is NO, stop and fix before proceeding.

Golden Rules

Tagging Configuration Resolution

Before applying ANY tags, the agent MUST follow this resolution order:

Step 1: Scan context/ for Customer-Supplied Tagging Standards

Search the context/ directory for any file containing tagging standards. The customer supplies their standards in whatever format they already have — the agent adapts to them, not the other way around.

Parsing rules:

• Look for recognizable tag keys: team, cost_center, business_unit, data_owner, data_classification, project, pii, class.*, or any custom keys
• Normalize all keys to snake_case
• Accept any reasonable structure — the agent interprets intent, not rigid schema
• If multiple files match, merge them (later file wins on conflicts)

Step 1b: Normalize to Canonical Internal Schema

After parsing the customer file, the agent normalizes all extracted values into the canonical schema defined in references/canonical-tagging-schema.yaml. This schema is never shown to the user — it is the agent's internal working format.

Normalization examples (any input → canonical schema):

The agent fills any fields not provided by the customer using smart defaults (Step 2 below).

Step 2: Derive Smart Defaults (No Customer Config Found, or Gaps in Config)

If no tagging file is found in context/, OR the customer file has gaps (e.g., they specify team and cost_center but not data_owner), the agent fills missing fields with meaningful values derived from project context:

Key difference from v1: Only cost_center gets a placeholder — all other tags get real derived values.

Step 3: PII Column Inference (Always Active)

Whether or not customer config is supplied, the agent always scans column names from the schema CSV (or YAML designs) and applies Databricks Data Classification class.* system governed tags using column name pattern matching:

Rules for PII inference:

• Always apply inferred PII tags regardless of whether customer config exists
• If customer config explicitly declares PII columns, those take precedence over inference (customer may override or suppress)
• Use class.* system governed tags (not custom pii/pii_type tags) for compatibility with Databricks Data Classification
• Customer can suppress a false positive by adding exclude_pii: [column_name] in their config
• Also recommend enabling Databricks Data Classification on the catalog for automated AI-powered scanning beyond column name patterns

Step 4: Environment Tag (Always Automatic)

The environment tag is always ${bundle.target} — never hardcoded. This is non-negotiable regardless of config.

Step 4b: Job / Pipeline Name Prefix (Non-Negotiable)

Every job and pipeline name: field MUST begin with the user-prefixed token [${bundle.target} ${var.user_prefix}] — this is the single canonical prefix across all layers (Bronze, Silver, Gold, ML, semantic, monitoring). Rules:

• The bundle MUST declare the user_prefix variable (default ${workspace.current_user.short_name}), so dev renders [dev jsmith] ….
• Do NOT rely on mode: development auto-prefixing; set presets.name_prefix: "" on the dev target so the explicit token is the sole authority (prevents [dev jsmith] [dev jsmith] … doubling).
• Prod keeps names clean by setting user_prefix: "" in the prod target.
• The project/domain token stays in the name after the prefix (e.g. [dev jsmith] Wanderbricks Bronze Layer - Clone).

Authoritative definition: skills/databricks-asset-bundles/SKILL.md → "Shared Workspace Naming".

Step 5: Consistency Enforcement

All tags must be consistent across all assets in the project:

Internal Reference

The canonical schema the agent normalizes to is defined in references/canonical-tagging-schema.yaml. This file is an agent-internal reference — the user never sees or fills it in. The user simply drops their tagging standards into context/ in whatever format they prefer.

Part 1: Naming Conventions

Object Naming Patterns

Never use: camelCase, PascalCase, SCREAMING_CASE, kebab-case, or spaces.

Table Prefixes

Approved Abbreviations (Use ONLY These)

id, ts, dt, amt, qty, pct, num, cnt, avg, min, max, pk, fk, dim, fact, agg, stg

Forbidden: cust, prod, inv, trans, ord, emp -- spell these out.

Column Patterns

For detailed naming examples, see references/naming-conventions.md.

Part 2: Comment Conventions

CM-01: SQL Block Comments

All DDL must include /* */ block comments with purpose, grain, and source:

/*
 * Table: dim_customer
 * Layer: Gold | Domain: Sales
 * Grain: One row per customer per effective period.
 * Source: Silver layer silver_customers table.
 */

CM-02: Table COMMENT (Dual-Purpose Format)

[One-line description]. Business: [use cases, consumers]. Technical: [grain, source, update frequency].

Note: Square brackets [] above are placeholders — replace with actual content. Do not include literal brackets in the output.

Examples:

-- Gold Dimension
COMMENT ON TABLE gold.dim_customer IS
'Customer dimension with SCD Type 2 history tracking. Business: Primary customer reference for segmentation and cohort analysis. Technical: MD5 surrogate key, is_current flag, daily merge from Silver.';

-- Gold Fact
COMMENT ON TABLE gold.fact_orders IS
'Daily order facts at customer-product-day grain. Business: Primary source for revenue reporting and sales dashboards. Technical: Composite PK, incremental merge, CDF enabled.';

CM-03: Column COMMENT (Dual-Purpose Format)

[Brief definition]. Business: [how it's used]. Technical: [data type notes, source, calculation].

customer_key STRING NOT NULL
COMMENT 'Surrogate key for SCD Type 2 versioning. Business: Used for joining fact tables. Technical: MD5 hash of customer_id + effective_from.';

total_amount DECIMAL(18,2)
COMMENT 'Total order amount after discounts in USD. Business: Primary revenue metric. Technical: SUM(quantity * unit_price * (1 - discount_pct)).';

CM-04: TVF COMMENT (v3.0 Structured Format)

COMMENT '
• PURPOSE: [One-line description of what the function returns].
• BEST FOR: [Query type 1] | [Query type 2] | [Query type 3]
• NOT FOR: [What to use instead] (use [alternative] instead)
• RETURNS: [PRE-AGGREGATED or DETAIL rows]
• PARAMS: [param1 (format)], [param2 (format)]
• SYNTAX: SELECT * FROM function_name(''param1'', ''param2'')
• NOTE: [Critical usage notes]
'

Metric View COMMENT Format (YAML)

comment: >
  PURPOSE: Cost analytics for billing analysis.
  BEST FOR: Total spend by workspace | Cost by SKU | Daily trends
  NOT FOR: Commit tracking (use commit_tracking) | Real-time alerts (use TVF)
  DIMENSIONS: usage_date, workspace_name, sku_name
  MEASURES: total_cost, total_dbus, tag_coverage_pct
  SOURCE: fact_usage (billing domain)
  JOINS: dim_workspace, dim_sku
  NOTE: Costs are list prices. Actual billed amounts may differ.

For complete comment examples, see references/comment-templates.md.

Part 3: Tagging Standards

Config-aware: Tag values come from customer-supplied config (any format) when available. When absent, the agent derives meaningful defaults from project context. See Tagging Configuration Resolution above.

TG-01: Workflow Tags (Asset Bundles)

All jobs and pipelines must include:

With customer config (values sourced from customer file in context/):

resources:
  jobs:
    gold_merge_job:
      tags:
        team: platform-engineering         # From customer tagging standards
        cost_center: CC-9901               # From customer tagging standards
        environment: ${bundle.target}      # Always automatic
        project: wanderbricks              # From customer tagging standards
        layer: gold                        # Auto-derived
        job_type: merge                    # Auto-derived

Without customer config (meaningful defaults):

resources:
  jobs:
    gold_merge_job:
      tags:
        team: data-engineering             # Default — add tagging config to context/ to customize
        cost_center: REVIEW-REQUIRED       # TODO: Add tagging config to context/ with cost_center
        environment: ${bundle.target}      # Always automatic
        project: wanderbricks              # Inferred from schema CSV (samples.wanderbricks)
        layer: gold                        # Auto-derived
        job_type: merge                    # Auto-derived

TG-02: Databricks Data Classification Tags (PII Columns)

Use Databricks Data Classification class.* system governed tags for PII — not custom pii/pii_type tags.

Supported class.* tags (global):

PII tags are always inferred from column names AND from customer config (if supplied). Customer config takes precedence — they can add, override, or suppress inferred tags.

-- Applied to columns based on name pattern inference + customer config
ALTER TABLE gold.dim_guest ALTER COLUMN email SET TAGS ('class.email_address' = '');
ALTER TABLE gold.dim_guest ALTER COLUMN phone_number SET TAGS ('class.phone_number' = '');
ALTER TABLE gold.dim_guest ALTER COLUMN guest_name SET TAGS ('class.name' = '');

-- Also recommend enabling automated Data Classification on the catalog:
-- Navigate to catalog > Details > Data Classification toggle > Enable

TG-03: Unity Catalog Governed Tags (Catalogs, Schemas, Tables)

With customer config:

ALTER CATALOG wanderbricks SET TAGS ('cost_center' = 'CC-9901', 'business_unit' = 'Hospitality');
ALTER SCHEMA wanderbricks.gold SET TAGS ('data_owner' = 'data-platform@wanderbricks.com');
ALTER TABLE gold.dim_guest SET TAGS ('data_classification' = 'confidential');
ALTER TABLE gold.fact_bookings SET TAGS ('data_classification' = 'internal');

Without customer config (meaningful defaults):

ALTER CATALOG wanderbricks SET TAGS ('cost_center' = 'REVIEW-REQUIRED');  -- TODO: Add tagging config to context/
ALTER CATALOG wanderbricks SET TAGS ('business_unit' = 'hospitality');     -- Inferred from domain
ALTER SCHEMA wanderbricks.gold SET TAGS ('data_owner' = 'wanderbricks-data-team');  -- Derived from project
ALTER TABLE gold.dim_guest SET TAGS ('data_classification' = 'internal');  -- Safe default

TG-04: Serverless Budget Policies

Serverless compute resources require budget policies with team, cost_center, and environment tags. If a named policy is specified in the customer config, reference it in Asset Bundles.

For tag query patterns and serverless cost attribution, see references/tagging-patterns.md.

Validation Checklist

Tagging Config Resolution

• Scanned context/ for customer tagging files in any format (YAML, CSV, MD, JSON, TXT)
• If config found: parsed and applied customer values (all tag keys normalized to snake_case)
• If config absent: derived meaningful defaults from project context (not lazy placeholders)
• Only cost_center uses REVIEW-REQUIRED placeholder (everything else gets a real derived value)
• environment tag is ${bundle.target} (never hardcoded)

PII / Data Classification

• Column names scanned for PII patterns and class.* system governed tags applied
• Used class.* tags (NOT custom pii/pii_type tags)
• Customer PII declarations (if any) take precedence over inference
• Recommended enabling Databricks Data Classification on the catalog

Naming

• All objects use snake_case
• Tables have correct prefix (dim_, fact_, bronze_, silver_)
• Only approved abbreviations used
• Columns follow standard patterns (PK, FK, boolean, SCD2)
• Jobs/pipelines follow naming format
• Every job/pipeline name: starts with [${bundle.target} ${var.user_prefix}] and the bundle declares the user_prefix variable (dev renders [dev <short_name>] …)

Comments

• DDL includes /* */ block comments
• All tables have dual-purpose COMMENT
• All columns have dual-purpose COMMENT
• TVFs have v3.0 structured COMMENT
• Metric views have structured comment in YAML

Tags

• All jobs have team, cost_center, environment tags
• All pipelines have required tags
• Catalogs tagged with cost_center and business_unit
• Schemas tagged with data_owner
• Confidential tables tagged with data_classification
• PII columns tagged with class.* governed tags (inferred + customer-declared)
• Tag values consistent across all project assets (same team, cost_center, project everywhere)

Additional Resources

• For detailed naming conventions and forbidden patterns, see references/naming-conventions.md
• For complete comment templates with examples, see references/comment-templates.md
• For tagging patterns and cost query SQL, see references/tagging-patterns.md