Skip to main content

OSI semantic layer documents Beta

💡Did you know...
Available from dbt v1.12 or with the dbt "Latest" release track.

dbt Core v1.12 and higher supports the Open Semantic Interchange (OSI) standard for defining semantic models and metrics. You can place OSI-format .json files in an OSI/ directory at the root of your project, and dbt parses them into the manifest alongside any native dbt semantic models. OSI-sourced definitions and native dbt semantic models can coexist in the same project.

Prerequisites​

  • You must be on dbt Core v1.12 or higher.
  • OSI documents must use version 0.1.0 or 0.1.1. Any other version string raises a parse error.

Defining semantic models using OSI documents​

To define semantic models with OSI documents:

  1. Create an OSI/ directory at the root of your dbt project, at the same level as dbt_project.yml.

  2. Add one or more OSI .json files to the directory. You can organize files into subdirectories; dbt scans the entire OSI/ directory tree.

    The source field must be the fully qualified warehouse location of a dbt model in this project, in the form database.schema.alias (for example, my_database.my_schema.fct_orders). dbt matches each dataset on database, schema, and model alias. Each dataset source must resolve to a dbt model. For restrictions on dataset sources, refer to Limitations.

    The following is an example OSI document that defines a semantic model on a dbt model called fct_orders:

    {
      "version": "0.1.1",
      "semantic_model": [
        {
          "name": "orders",
          "datasets": [
            {
              "name": "orders",
              "source": "my_database.my_schema.fct_orders"
            }
          ]
        }
      ]
    }

    This example defines a semantic model only. To add metrics, include a metrics array on the semantic model per the OSI specification.

  3. Run any command that triggers compilation, such as dbt compile or dbt run. dbt automatically discovers and parses OSI files.

The resulting semantic models (and metrics, when defined in your OSI documents) appear in dbt artifacts in your target/ directory, including manifest.json, semantic_manifest.json, and osi_document.json.

Limitations​

  • dbt scans only the root project's OSI/ directory. OSI files in installed dependency packages are ignored.
  • Each OSI dataset source must resolve to a dbt model. OSI documents that reference sources, seeds, snapshots, or external tables are not supported.
  • If the OSI converter encounters unsupported metric types or other constructs, those elements are dropped and dbt emits a warning (event code I078), but parsing continues. Warnings appear in the CLI and in logs/dbt.log; for more information, refer to Events and logs.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading