dbt-labs / dbt-labs/dbt

[Bug] Setting `osi-paths` in dbt_project.yml fires CustomTopLevelKeyDeprecation (key missing from project jsonschema)

Open
#15,645 2 comments 0 reactions 1 assignee Claimed by @akbog View on GitHub
area:engine engine:v2 type:bug
Dominant language
Rust
Stars
13.8k
Forks
2.6k
Avg merge
21h 31m
Merged PRs (30d)
56

Description

### Is this a new bug in dbt-core?

- [x] I believe this is a new bug in dbt-core
- [x] I have searched the existing issues, and I could not find an existing issue for this bug

### Current Behavior

Setting the `osi-paths` top-level key in `dbt_project.yml` fires `CustomTopLevelKeyDeprecation`:

```
[WARNING][CustomTopLevelKeyDeprecation]: Deprecated functionality
Unexpected top-level key `osi-paths` in file `.../dbt_project.yml`
```

For projects that promote deprecations to errors (`flags.warn_error_options.error: ["Deprecations"]`), this makes the documented key unusable — `dbt parse` hard-fails with a Compilation Error before doing anything.

### Expected Behavior

`osi-paths` is a legitimate top-level key: it exists on the project contract (`osi_paths`, serialized as `"osi-paths"`), it is consumed by `dbt/config/project.py` (defaulting to `["osi", "OSI"]`), and it works as documented in #13093 / #13088 — the OSI documents in the configured directory are parsed into the manifest correctly. It should not be reported as an "unexpected top-level key".

### Steps To Reproduce

1. dbt-core 1.12.0, any adapter.
2. Add to `dbt_project.yml`:

```yaml
osi-paths: ["semantic/osi"]

flags:
warn_error_options:
error:
- "Deprecations"
```

3. Run `dbt parse` → Compilation Error via `CustomTopLevelKeyDeprecation`. Without the `warn_error_options` promotion, the same run emits the deprecation warning while the key itself works fine.

### Root cause (from reading the installed package)

The project jsonschemas used by the top-level-key check don't include `osi-paths`:

```python
>>> import json
>>> s = json.load(open("dbt/jsonschemas/project/latest.json"))
>>> "osi-paths" in s["properties"], "model-paths" in s["properties"]
(False, True)
```

Same for `dbt/jsonschemas/project/0.0.85.json`, and a GitHub code search for `"osi-paths" extension:json` in this repo returns zero results, so the schema appears not to be fixed on any branch yet. The key was added to the contract in #13093 (backported to 1.12.latest in #15146), but the jsonschema wasn't updated alongside it.

### Workaround

Silence the false positive while keeping every other deprecation fatal:

```yaml
flags:
warn_error_options:
error:
- "Deprecations"
silence:
- "CustomTopLevelKeyDeprecation"
- "DeprecationsSummary"
```

(`DeprecationsSummary` also has to be silenced because it re-raises at the end of parse even when the only encountered deprecation events are silenced ones — arguably a second, smaller bug.)

### Environment

- OS: macOS 15
- Python: 3.12
- dbt-core: 1.12.0 (also verified the schema omission on the `1.12.latest` branch)
- dbt-bigquery: 1.12.0

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.