dbtective documentation
Rules
property_file_colocation

property_file_colocation

Rule: property_file_colocation


property_file_colocation details
This rule checks that property (YAML) files are colocated with the object's primary file (SQL, CSV, etc.). It helps enforce a consistent project structure where schema definitions live alongside the code they describe.

Two modes are available:

  • same_directory (default) — the property file must be in the same directory as the primary file.
  • relative_subdirectory — the property file may live in one of the specified allowed_subdirectories beneath the primary file’s directory.

Configuration

  • type: Must be property_file_colocation.
  • mode: (optional) Colocation strategy.
    • Default: same_directory
    • Options: same_directory, relative_subdirectory
  • allowed_subdirectories: (optional) List of subdirectory names allowed when using relative_subdirectory mode. If empty or omitted, falls back to same_directory behavior.
  • applies_to: (optional) List of dbt object types to include.
    • Default: ["models", "seeds", "snapshots", "sources", "macros", "exposures"]
    • Options: models, seeds, snapshots, sources, macros, exposures
Common Rule Config
  • name: Human-readable name of the rule.
  • severity: "error" (fail) or "warning" (warn only).
    • (optional, defaults to "error" if not specified)
  • description: Human-readable explanation of the rule.
  • category: Override the default rule category. Included in structured output (JSON, CSV, NDJSON) but not in the CLI table. Each rule has a built-in default (e.g. documentation, naming, testing, governance, structure, performance).
    • (optional, defaults to the rule type's built-in category)
  • includes: List of patterns to explicitly include for this rule. See Includes & Excludes for pattern syntax and examples.
  • excludes: List of patterns to explicitly exclude from this rule. See Includes & Excludes for pattern syntax and examples.
  • model_materializations: Filter models by materialization type. Only applies when applies_to includes models.
    • (optional, if not specified all materializations are included)
    • Built-in types: table, view, incremental, ephemeral, materialized_view. Custom materializations are also supported.
    • Example: ["table", "incremental"]

Example Config

manifest_tests:
  # Ensure YAML files are in the same directory as their SQL files
  - name: "yaml_colocation"
    type: "property_file_colocation"
    description: "Property files must be colocated with their SQL files"
    severity: "warning"
    applies_to: ["models"]

  # Allow YAML files in a 'properties' subdirectory
  - name: "yaml_in_properties_folder"
    type: "property_file_colocation"
    description: "Property files must be in a 'properties' subdirectory"
    mode: "relative_subdirectory"
    allowed_subdirectories:
      - "properties"
      - "schema"
[[manifest_tests]]
name = "yaml_colocation"
type = "property_file_colocation"
description = "Property files must be colocated with their SQL files"
severity = "warning"
applies_to = ["models"]

[[manifest_tests]]
name = "yaml_in_properties_folder"
type = "property_file_colocation"
description = "Property files must be in a 'properties' subdirectory"
mode = "relative_subdirectory"
allowed_subdirectories = ["properties", "schema"]
[[tool.dbtective.manifest_tests]]
name = "yaml_colocation"
type = "property_file_colocation"
description = "Property files must be colocated with their SQL files"
severity = "warning"
applies_to = ["models"]

[[tool.dbtective.manifest_tests]]
name = "yaml_in_properties_folder"
type = "property_file_colocation"
description = "Property files must be in a 'properties' subdirectory"
mode = "relative_subdirectory"
allowed_subdirectories = ["properties", "schema"]
Relevant dbt structure

Same directory mode — YAML file alongside SQL:

      • stg_orders.sql
      • _stg_orders.yml ✓ same directory

    • Relative subdirectory mode — YAML in an allowed subdirectory:

      • stg_orders.sql
        • _stg_orders.yml ✓ allowed subdirectory

    • Violation — YAML in a different directory:

      • stg_orders.sql
    • schema.yml ✗ not colocated
    • Rulessources_have_freshness