Improve error message for unknown fields in semantic_model config

When a user adds an unknown field (e.g. description) inside the
semantic_model: config object, replace the opaque JSON Schema error
"is not valid under any of the given schemas" with a clear message
naming the offending field and listing the valid ones.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: theyostalservice

core/dbt/contracts/graph/unparsed.py

@@ -551,6 +551,19 @@ class UnparsedSemanticModelConfig(dbtClassMixin):
     group: Optional[str] = None
     config: Optional[UnparsedSemanticResourceConfig] = None
 
+    @classmethod
+    @override
+    def validate(cls, data: Any) -> None:
+        if isinstance(data, dict):
+            allowed = set(cls.__dataclass_fields__.keys())
+            extra = set(data.keys()) - allowed
+            if extra:
+                raise ValidationError(
+                    f"Unknown field(s) in semantic_model config: {', '.join(sorted(extra))}. "
+                    f"Valid fields are: {', '.join(sorted(allowed))}."
+                )
+        super().validate(data)
+
 
 @dataclass
 class UnparsedModelUpdate(UnparsedNodeUpdate):
@@ -570,6 +583,18 @@ class UnparsedModelUpdate(UnparsedNodeUpdate):
     metrics: Optional[List[UnparsedMetricV2]] = None
     derived_semantics: Optional[UnparsedDerivedSemantics] = None
 
+    @classmethod
+    @override
+    def validate(cls, data: Any) -> None:
+        # Validate the semantic_model sub-object before the full JSON Schema runs so
+        # that unknown fields produce a clear error instead of the opaque JSON Schema
+        # message "is not valid under any of the given schemas".
+        if isinstance(data, dict):
+            sm = data.get("semantic_model")
+            if isinstance(sm, dict):
+                UnparsedSemanticModelConfig.validate(sm)
+        super().validate(data)
+
     def __post_init__(self) -> None:
         if self.latest_version:
             version_values = [version.v for version in self.versions]

tests/functional/semantic_models/fixtures.py

@@ -1102,3 +1102,29 @@
           type: categorical
           expr: id
 """
+
+# Reproduces: error when description (or other unknown field) is placed inside
+# the semantic_model: config object.
+customer_yaml_semantic_model_with_description = """
+models:
+  - name: fct_revenue
+    description: This model provides a detailed view of purchase transactions.
+    semantic_model:
+      enabled: true
+      name: purchases
+      description: purchases semantic model
+    agg_time_dimension: ds
+    columns:
+      - name: id
+        entity:
+          name: id_entity
+          type: primary
+        dimension:
+          name: id_dim
+          type: categorical
+      - name: second_col
+        granularity: day
+        dimension:
+          name: ds
+          type: time
+"""

tests/functional/semantic_models/test_semantic_model_v2_parsing.py

@@ -14,6 +14,7 @@
 from tests.functional.semantic_models.fixtures import (
     base_schema_yml_v2,
     base_schema_yml_v2_with_custom_sm_name,
+    customer_yaml_semantic_model_with_description,
     derived_semantics_with_doc_jinja_yml,
     derived_semantics_yml,
     fct_revenue_sql,
@@ -992,3 +993,25 @@ def test_metrics_use_model_name_as_semantic_model_name(self, project):
 
 # TODO DI-4605: add enforcement and a test for when there are validity params with no column granularity
 # TODO DI-4603: add enforcement and a test for a TIME type dimension and a column that has no granularity set
+
+
+class TestSemanticModelConfigUnknownFieldClearError:
+    """Verifies that unknown fields inside semantic_model: config produce a clear error message
+    naming the offending field and the valid fields, instead of the opaque JSON Schema error
+    'is not valid under any of the given schemas'."""
+
+    @pytest.fixture(scope="class")
+    def models(self):
+        return {
+            "schema.yml": customer_yaml_semantic_model_with_description,
+            "fct_revenue.sql": fct_revenue_sql,
+            "metricflow_time_spine.sql": metricflow_time_spine_sql,
+        }
+
+    def test_unknown_field_in_semantic_model_config_gives_clear_error(self, project) -> None:
+        runner = dbtTestRunner()
+        result = runner.invoke(["parse"])
+        assert not result.success
+        error_msg = str(result.exception)
+        assert "Unknown field(s) in semantic_model config: description" in error_msg
+        assert "Valid fields are:" in error_msg