Naming policy and CAF defaults.

ContractForge uses a deterministic naming policy for generated artifacts. CAF-style naming is the default reference when the user does not provide an explicit organization-specific policy.

What CAF means in ContractForge

CAF refers to the Cloud Adoption Framework naming style: names should be deterministic, readable, environment-aware and consistent across teams. ContractForge uses that idea as a default baseline for generated names such as auxiliary artifacts, control assets and template output.

Physical target names are not silently rewritten

If the contract explicitly defines target.catalog, target.schema and target.table, those identifiers remain the source of truth. Naming policy affects derived/generated names unless an explicit override says otherwise.

Why naming is part of the contract

Reviewability

Generated artifacts should be predictable in pull requests and operational reviews.

Multi-team consistency

Teams can share defaults without copying naming rules into every notebook.

Environment separation

Development, staging and production names can include controlled tokens instead of ad-hoc suffixes.

Safe overrides

Explicit names still win when a company already has a catalog or table naming standard.

Where naming applies

Area	Behavior	Typical example
Target table	Explicit contract value is preserved.	main.crm_curated.s_customers
Control schema	Can be derived from environment/domain when not supplied by configuration.	ops_contractforge_dev
Quarantine tables	Can derive from target context and run classification.	q_s_customers
Template output	Uses naming policy to create predictable contract filenames and starter tables.	silver/s_customers.ingestion.yaml
Generated support artifacts	Uses stable tokens to avoid collision and make lineage obvious.	cf_dev_sales_orders_state

Default policy

The default policy is intentionally conservative. It normalizes tokens, removes unsafe characters, keeps names lowercase by default and avoids changing physical names that the user already declared.

Rule	Default	Reason
Case	Lowercase generated names.	Reduces cross-runtime and SQL quoting friction.
Separator	Underscore.	Readable in SQL, files and dashboards.
Unsafe characters	Normalized or removed.	Prevents invalid catalog/table/file identifiers.
Explicit physical names	Preserved.	Contracts must not surprise users by renaming target objects.
CAF baseline	Used when deriving names.	Provides an enterprise-friendly convention without forcing a custom standard.

Contract configuration

Use the naming block when a project needs generated names to follow organization-specific tokens or when a generated artifact needs an explicit override.

YAML

target:
  catalog: main
  schema: crm_curated
  table: s_customers

layer: silver
domain: crm

naming:
  policy: caf
  environment: dev
  product: customer360
  component: ingestion
  separator: _
  lowercase: true
  overrides:
    quarantine_table: q_s_customers
    state_table: cf_dev_crm_s_customers_state

Python

from contractforge import ingest

result = ingest(
    catalog="main",
    target_schema="crm_curated",
    target_table="s_customers",
    layer="silver",
    domain="crm",
    naming={
        "policy": "caf",
        "environment": "dev",
        "product": "customer360",
        "component": "ingestion",
        "separator": "_",
        "lowercase": True,
        "overrides": {
            "quarantine_table": "q_s_customers",
            "state_table": "cf_dev_crm_s_customers_state",
        },
    },
    source={"type": "table", "name": "main.raw.b_customers"},
    mode="hash_diff_upsert",
    merge_keys=["customer_id"],
)

How to choose a policy

Situation	Recommended choice
No company naming standard exists yet.	Use the CAF default and keep explicit target names in the contract.
A company already has table prefixes or catalog rules.	Keep those rules in target and use naming policy only for derived artifacts.
Different teams use different domains.	Include stable domain/product/environment tokens in the policy.
A generated name must match an existing object.	Use an explicit override instead of relying on derivation.

Design rule

Naming policy should make generated artifacts predictable, not hide physical decisions. The contract should still show the real target catalog, schema and table that will be written.