Enforce dimensions have 'validity_params' only if they have granularity (#12473)

* Enforce dimensions have 'validity_params' only if they have granularity

* Add enforcement for derived dimensions, too

* Add changie file.

Author: theyostalservice

.changes/unreleased/Fixes-20260210-154042.yaml

@@ -0,0 +1,6 @@
+kind: Fixes
+body: Provide user-friendly validations that dimensions with 'validity_params' also have granularities.
+time: 2026-02-10T15:40:42.808774-08:00
+custom:
+    Author: theyostalservice
+    Issue: "12473"

core/dbt/contracts/graph/unparsed.py

@@ -188,6 +188,18 @@ class UnparsedDerivedDimensionV2(UnparsedDimensionV2):
     expr: str
     granularity: Optional[str] = None  # str is really a TimeGranularity Enum
 
+    @classmethod
+    @override
+    def validate(cls, data):
+        super().validate(data)
+        # validity_params may only be set when the derived dimension has a granularity
+        if data.get("validity_params") is not None and not data.get("granularity"):
+            dim_name = data.get("name")
+            raise ValidationError(
+                f"Derived dimension {dim_name} has validity_params, "
+                "so it must specify a granularity."
+            )
+
 
 @dataclass
 class UnparsedEntityBase(dbtClassMixin):
@@ -253,6 +265,18 @@ def validate(cls, data):
                     f"column {data.get('name')}, "
                     "so that column must specify a granularity."
                 )
+            # validity_params may only be set when the column has a granularity
+            if (
+                isinstance(dimension, dict)
+                and dimension.get("validity_params") is not None
+                and not data.get("granularity")
+            ):
+                dim_name = dimension.get("name") or data.get("name")
+                raise ValidationError(
+                    f"Dimension {dim_name} has validity_params attached to "
+                    f"column {data.get('name')}, "
+                    "so that column must specify a granularity."
+                )
 
 
 @dataclass

tests/unit/contracts/graph/test_unparsed.py

@@ -21,6 +21,7 @@
     HasColumnTests,
     UnparsedColumn,
     UnparsedConversionTypeParams,
+    UnparsedDerivedDimensionV2,
     UnparsedDocumentationFile,
     UnparsedExposure,
     UnparsedMacro,
@@ -1140,7 +1141,8 @@ def test_column_parse():
 
 
 class TestUnparsedColumnTimeDimensionGranularityValidation(ContractTestCase):
-    """Test validation that SL YAML V2 column with time dimension must specify granularity."""
+    """Test validation that SL YAML V2 column with time dimension must specify granularity,
+    and that dimension validity_params require granularity."""
 
     ContractType = UnparsedColumn
 
@@ -1189,3 +1191,80 @@ def test_non_time_dimension_string_passes_without_granularity(self):
         col = self.ContractType.from_dict(column_dict)
         self.assertEqual(col.name, "category")
         self.assertIsNone(col.granularity)
+
+    def test_dimension_with_validity_params_without_granularity_fails_validation(self):
+        """Dimension (dict) with validity_params must have column granularity."""
+        column_dict = {
+            "name": "valid_from",
+            "dimension": {
+                "type": "time",
+                "name": "valid_from_dim",
+                "validity_params": {"is_start": True, "is_end": False},
+            },
+        }
+        self.assert_fails_validation(column_dict)
+
+    def test_dimension_with_validity_params_with_granularity_passes_validation(self):
+        """Dimension (dict) with validity_params and granularity passes."""
+        column_dict = {
+            "name": "valid_from",
+            "granularity": "day",
+            "dimension": {
+                "type": "time",
+                "name": "valid_from_dim",
+                "validity_params": {"is_start": True, "is_end": True},
+            },
+        }
+        col = self.ContractType.from_dict(column_dict)
+        self.assertEqual(col.granularity, "day")
+        self.assertEqual(col.name, "valid_from")
+
+    def test_dimension_without_validity_params_passes_without_granularity_when_not_time(self):
+        """Dimension (dict) without validity_params and not time does not require granularity."""
+        column_dict = {
+            "name": "category",
+            "dimension": {"type": "categorical", "name": "category_dim"},
+        }
+        col = self.ContractType.from_dict(column_dict)
+        self.assertEqual(col.name, "category")
+        self.assertIsNone(col.granularity)
+
+
+class TestUnparsedDerivedDimensionV2ValidityParamsValidation(ContractTestCase):
+    """Test validation that UnparsedDerivedDimensionV2 only has validity_params when it has granularity."""
+
+    ContractType = UnparsedDerivedDimensionV2
+
+    def test_derived_dimension_with_validity_params_without_granularity_fails_validation(self):
+        """Derived dimension with validity_params must have granularity."""
+        dimension_dict = {
+            "type": "time",
+            "name": "valid_from_dim",
+            "expr": "valid_from",
+            "validity_params": {"is_start": True, "is_end": False},
+        }
+        self.assert_fails_validation(dimension_dict)
+
+    def test_derived_dimension_with_validity_params_with_granularity_passes_validation(self):
+        """Derived dimension with validity_params and granularity passes."""
+        dimension_dict = {
+            "type": "time",
+            "name": "valid_from_dim",
+            "expr": "valid_from",
+            "granularity": "day",
+            "validity_params": {"is_start": True, "is_end": True},
+        }
+        dim = self.ContractType.from_dict(dimension_dict)
+        self.assertEqual(dim.granularity, "day")
+        self.assertEqual(dim.name, "valid_from_dim")
+
+    def test_derived_dimension_without_validity_params_passes_without_granularity(self):
+        """Derived dimension without validity_params does not require granularity."""
+        dimension_dict = {
+            "type": "time",
+            "name": "some_dim",
+            "expr": "some_column",
+        }
+        dim = self.ContractType.from_dict(dimension_dict)
+        self.assertEqual(dim.name, "some_dim")
+        self.assertIsNone(dim.granularity)