Skip to content

Improve error message for unknown fields in semantic_model config#12766

Merged
QMalcolm merged 2 commits intomainfrom
patricky/semantic-model-better-errors
Apr 1, 2026
Merged

Improve error message for unknown fields in semantic_model config#12766
QMalcolm merged 2 commits intomainfrom
patricky/semantic-model-better-errors

Conversation

@theyostalservice
Copy link
Copy Markdown
Contributor

@theyostalservice theyostalservice commented Apr 1, 2026

Why

When a user adds an unsupported field inside the `semantic_model:` config object (e.g. `description:`, which the docs incorrectly showed as valid), dbt produces an unhelpful error:

```
at path ['semantic_model']: {'enabled': True, 'name': 'purchases', 'description': '...'} is not valid under any of the given schemas
```

The `anyOf` JSON Schema failure gives no indication of which field is wrong or what is allowed.

What

  • `UnparsedSemanticModelConfig.validate()` — checks for unknown fields and raises `ValidationError` with a message naming the offending field(s) and listing the valid ones
  • `UnparsedModelUpdate.validate()` — calls the nested validator before the full JSON Schema so the clear error fires first

After this change the error reads:

```
Unknown field(s) in semantic_model config: description. Valid fields are: config, enabled, group, name.
```

Tests:

  • `tests/unit/utils/init.py`: adds `assert_fails_validation_with_message()` helper to `ContractTestCase` for asserting both that validation fails and that the error message is actionable — intended for reuse as we improve errors on other unparsed objects
  • `tests/unit/contracts/graph/test_unparsed.py`: adds `TestUnparsedSemanticModelConfig` with four unit tests covering valid config, single extra field, message lists valid fields, and multiple extra fields

Refs

Drafted by claude-sonnet-4-6 under the direction of @theyostalservice

@cla-bot cla-bot bot added the cla:yes label Apr 1, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 1, 2026

Thank you for your pull request! We could not find a changelog entry for this change. For details on how to document a change, see the contributing guide.

@codecov
Copy link
Copy Markdown

codecov bot commented Apr 1, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.43%. Comparing base (eee9587) to head (1ddae80).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main   #12766      +/-   ##
==========================================
+ Coverage   91.41%   91.43%   +0.01%     
==========================================
  Files         203      203              
  Lines       25844    25853       +9     
==========================================
+ Hits        23626    23639      +13     
+ Misses       2218     2214       -4     
Flag Coverage Δ
integration 88.30% <33.33%> (+0.01%) ⬆️
unit 65.57% <100.00%> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components Coverage Δ
Unit Tests 65.57% <100.00%> (+0.01%) ⬆️
Integration Tests 88.30% <33.33%> (+0.01%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

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>
@theyostalservice theyostalservice force-pushed the patricky/semantic-model-better-errors branch from ebd3c67 to 937554d Compare April 1, 2026 22:36
@theyostalservice theyostalservice marked this pull request as ready for review April 1, 2026 23:08
@theyostalservice theyostalservice requested a review from a team as a code owner April 1, 2026 23:08
@QMalcolm QMalcolm added the user docs [docs.getdbt.com] Needs better documentation label Apr 1, 2026
Copy link
Copy Markdown
Contributor

@QMalcolm QMalcolm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Thank you for doing this work!

@QMalcolm QMalcolm merged commit 6118dee into main Apr 1, 2026
129 of 131 checks passed
@QMalcolm QMalcolm deleted the patricky/semantic-model-better-errors branch April 1, 2026 23:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla:yes user docs [docs.getdbt.com] Needs better documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants