Ask three teams for "total revenue" and you will often get three numbers. On the TPC-H sample data that ships with every Snowflake account, five perfectly reasonable definitions give results between $109B and $230B:

Nobody made an error. Each dashboard, notebook and AI assistant simply encoded its own definition. This is metric drift, and it is one symptom of semantic fragmentation:

Open Semantic Interchange (OSI) is a vendor-neutral YAML specification for semantic models: datasets, keys, relationships, fields and metrics. The specification and its converters are developed in the open as Apache Ossie.

Be clear about what OSI is today. It is not a format that every tool reads natively. Snowflake can turn an OSI document directly into a semantic view. Most other tools are reached through open-source converters that translate OSI into their own proprietary format, and those converters are young. The value of OSI right now is architectural: one open definition that you own, version and test, from which every tool-specific format is generated rather than hand-maintained.

In this guide you:

1. Write the revenue definition once, in OSI, and compile it into a Snowflake semantic view that Cortex Analyst can use.
2. Prove the semantic view returns the right numbers.
3. Generate other tools' formats from the same file, and weigh how the model should bind to the data.

The tools used along the way are examples; the architectural pattern is what matters.

Before writing any YAML, it helps to see the problem the way an enterprise architect does.

A typical enterprise already has three to five semantic layers: one in the BI tool, one in the transformation framework, one in the notebook platform, and now one for every AI agent. Without a shared format, each pair of tools that must agree needs its own translation, maintained by hand. Three tools that define metrics and three that consume them already mean nine such translations, and every new tool adds a full row:

With OSI as the hub, there is one reviewed and tested source. Snowflake compiles it natively into a semantic view, which AI agents and tools that read semantic views use directly. Other tools get their own format generated by a converter, never edited by hand:

With a hub, adding a tool means adding one converter, not N new integrations. Proprietary formats stay, but they become build artifacts, like compiled binaries, rather than places where business logic is authored.

How much of this works today depends on the target; the section Portable versus Snowflake-specific covers it once you know the building blocks of a model.

Create a database for the semantic view and make sure the TPC-H sample data is available. Some accounts do not have SNOWFLAKE_SAMPLE_DATA mounted; the second statement fixes that.

Reproduce the drift for yourself:

Notice that the gap between "net" and "net, shipped only" comes from a filter, not a formula. A metric definition is the expression and its filters and its grain. That is exactly what we will pin down in OSI.

An OSI document describes one semantic model. Its building blocks map closely to how analysts already think:

Join order lines to orders and sum the order header amount, a mistake that is easy to make in a notebook:

Every order is counted once per line. Because the OSI model declares primary_key on each dataset and the direction of each relationship (from the many side to the one side), a semantic engine knows orders is at a coarser grain than lineitem and aggregates each metric at its own grain.

For this guide, the business agrees that revenue is extended price after discount, excluding returned lines, before tax. We encode it as a field plus a metric:

The filter lives in the field expression, so every consumer inherits it. O_TOTALPRICE stays in the model as total_price, but its description says explicitly: "Not revenue: never use it for revenue or sales questions."

Notice that the business meaning, including synonyms such as net sales, is written into description, on the field as well as the metric. The same synonyms also appear in ai_context, a field intended for AI tools. The section on Cortex Analyst explains why the model states things twice: in the current preview, Snowflake only acts on the description.

Two questions decide how portable a model is: which parts of the document are standard, and which tools can consume it. Within the document:

And on the consuming side, at the time of writing (verified while building this guide):

Most third-party tools do not import OSI directly today. They read their own format, and some read Snowflake semantic views natively. The converters target the in-development spec 0.2.0.dev0 and were not yet on PyPI. Treat them as early tooling: useful, inspectable, and worth testing before you trust them.

Two practical rules that we learned while testing this guide:

The complete model is in assets/tpch-revenue.osi.yaml. Pass it to the procedure, together with the schema that will hold the semantic view. The semantic view gets the model's name.

The $$ delimiters let you paste the YAML as-is, without escaping quotes. Most of the file repeats the patterns from the previous section. The parts worth reading closely are the keys and relationships, which give the semantic view its grain and join paths:

Note that source points straight at the shared sample database; the tables do not have to live in the same schema as the semantic view.

Query it like any semantic view:

The region dimension sits three relationships away from lineitem (lineitem → orders → customer → nation → region). The semantic view resolves those joins from the model; nobody writes them again.

The conversion also works in the other direction. This returns OSI YAML for any semantic view, including ones you built without OSI:

The output uses upper-case names and adds SNOWFLAKE vendor extensions such as access_modifier. Keys, relationships and descriptions are exported from native semantic view properties. ai_context comes back too, but only because it was stored verbatim in the OSI extension; the OSI datatype values are not exported. This export is what keeps Snowflake from becoming a lock-in point: any semantic view, including ones built without OSI, can leave as an open document. Keep the hand-written YAML in Git as the source of truth and treat the read-back as an export.

A shared definition is only useful if it is correct. Write each business question twice, once against the semantic view and once as independent reference SQL over the raw tables, and require zero differing rows.

All four tests should return diffs = 0. The orders_by_year test is the fan-out check: order_count is defined on orders, and stays correct even though revenue is measured on lineitem.

Run these tests every time the model changes, for example in a CI pipeline, and a definition can no longer drift silently.

The OSI procedure turns description into native COMMENTs on the semantic view, its facts, dimensions and metrics, and Cortex Analyst reads those. Ask a plain-language question in Snowsight (AI & ML » Cortex Analyst, select OSI_GUIDE.TPCH.TPCH_REVENUE) or through a Cortex Agent that uses the semantic view as a tool:

Cortex Analyst generates:

It picked net_revenue, not the tempting O_TOTALPRICE column. The AI assistant now reports the same number as the finance dashboard. The names and descriptions in the model did that work, not prompt engineering: the metric is called net_revenue, its basis net_amount_kept is described as the company definition of revenue, and total_price is described as "Not revenue".

The synonyms written into the descriptions work too:

In the current preview, only description grounds Cortex Analyst. It becomes a native COMMENT, and it works best on the field Analyst has to choose between. ai_context is kept only in the OSI extension of the semantic view for export, and Cortex Analyst ignores it. Put anything an AI tool must respect in description.

The Snowflake semantic view is one target compiled from the OSI file. Other tools have their own proprietary semantic formats. In the hub-and-spoke architecture you never author those formats by hand: you generate them from the OSI source, the way a compiler produces binaries for different platforms.

This guide uses two of the open-source converters in the Apache Ossie repository as examples: Hex semantic project YAML and dbt MetricFlow. They represent two common kinds of target, a BI tool's semantic layer and a transformation framework's metric layer. The pattern is the same for any other converter. How each tool then loads its generated files is that tool's own concern and outside the scope of this guide.

At the time of writing, the converters and their core library are not on PyPI. Install them from the repository:

The converters expect the in-development spec 0.2.0.dev0, which drops the semantic_model: list and puts the model at the document root. The Snowflake procedure only accepts 0.1.1. The content is identical, so generate the newer shape from your single source file:

This is itself an example of the pattern: one hand-edited file, other shapes generated in the build. When Snowflake supports the newer version, the step disappears.

The -d ansi_sql flag selects the expression dialect, which is why the model uses ANSI_SQL: portable expressions are what let one source feed many targets. Where a conversion succeeds, the business logic carries over unchanged. In the generated Hex YAML, for example:

Same table, same filter, same metric, same join direction. Whether a conversion fully succeeds is the subject of the next section.

An open standard does not make tools identical. Each proprietary format can express some things and not others. The architectural value of OSI is that those gaps become explicit and testable instead of silent. This section measures them for the two example targets.

The Hex export above reports:

The metrics and joins survive; the AI context and the composite key on lineitem do not. An earlier draft of this model had no datatype on most fields and produced 23 extra warnings, with prices typed as string in the target. Adding types fixed that.

Many enterprises already have metrics defined in another tool, and the most valuable use of a standard is to bring them over instead of rewriting them. dbt MetricFlow is a good test case. Converting to its format:

The converter refuses rather than producing a subtly wrong model. That is the right behaviour: the key defines the grain of lineitem, and the grain is what protects against fan-out. Removing the key would make the error go away by throwing that protection away. The proper fix is a single-column key, which is what the interface layer in the next section provides. Only to continue this experiment, a throwaway copy with the primary_key removed converts successfully. The converter even turns average_order_value into a proper MetricFlow ratio metric. Do not do this in a real model.

Now simulate the migration direction: take that manifest as if it were an existing project, convert it back to OSI and compile it into Snowflake:

Wrap from_dbt.yaml in the 0.1.1 shape, name the model tpch_from_dbt and deploy it with SYSTEM$CREATE_SEMANTIC_VIEW_FROM_OSSIE_YAML. Then run two queries:

The metric definition and its descriptions came through intact. All four relationships, the datatype values and the ai_context were lost. MetricFlow expresses joins through shared entity names, and the converter names each entity after its own key column (l_orderkey on one side, o_orderkey on the other), so nothing matches. Snowflake then refuses the cross-dataset query instead of returning a wrong number.

Many of the losses above trace back to how the model is bound to the data, not to the standard itself. The model points straight at physical tables, with their composite keys and inconsistent column names. That leaves an uncomfortable choice: keep the composite key and lose the conversion, or drop the key and lose the grain. The next section explores a design pattern that removes the dilemma.

So far the OSI model has read directly from the data layer: SNOWFLAKE_SAMPLE_DATA.TPCH_SF1. That is a perfectly valid way to work, and Snowflake semantic views accept tables and views alike. This section explores an alternative worth considering: a thin layer of views between the physical tables and the semantic model, so that the model binds to a stable interface instead of directly to storage.

This is a general architectural design pattern, not a Snowflake recommendation. Whether it is worth it depends on your situation. The case for it on this data set is concrete, though. The composite key on LINEITEM forced a choice between correctness and portability. A view that exposes a single-column key gives you both: the grain stays declared, and the conversion succeeds. The section shows what it changes, then weighs the benefits against the downsides.

Run assets/interface-views.sql. It creates five views in OSI_GUIDE.TPCH, next to the semantic views, which keeps grants for the domain in one schema. The views only rename, key and type the data:

Two design rules matter:

The business rule, excluding returned lines, deliberately stays in the OSI model and not in the view. Views express how data is stored; the model expresses what the business means. Hiding a definition in SQL would make it invisible to every other tool.

assets/tpch-revenue-if.osi.yaml is the same model bound to the views. Only the source lines, column names and keys change:

Deploy it as TPCH_REVENUE_IF with SYSTEM$CREATE_SEMANTIC_VIEW_FROM_OSSIE_YAML, then run the parity tests against OSI_GUIDE.TPCH.TPCH_REVENUE_IF, with the reference SQL still on the raw tables. All four return diffs = 0, so the views add no drift.

Generate the 0.2.0.dev0 copy and run both converters again:

In the MetricFlow manifest, the entities now line up: order_key is a foreign entity on order_line and the primary entity on sales_order, so MetricFlow can join them. Converted back to OSI, the model has all four relationships and five primary keys. Deploy it as TPCH_IF_FROM_DBT and run the parity tests: all four pass, including revenue by region, which failed before.

Read the table as the answer to the dilemma from the previous section. Nothing in the OSI model was weakened to get there. The grain is still declared and the business rule is unchanged. Only the binding to the data changed, and the generated model went from unusable for cross-dataset questions to passing every parity test.

The last row is the honest limit. Views fix structural problems such as keys, names and grain. They cannot make a target format carry metadata it has no slot for. That is a converter or target limitation, so keep catching it in the pipeline.

Benefits:

Downsides:

Binding directly to tables is the simpler choice when the tables are already a clean, well-named presentation layer, when the model only ever compiles to Snowflake, or when one team owns both the tables and the model. The interface layer pays off as the number of source systems, consuming tools or teams grows.

Suppose finance decides that revenue should also exclude lines that have not shipped yet. With OSI that is one edit, in one file:

In an enterprise setup, the pull request triggers a pipeline:

1. Review: the finance data owner approves the change to the OSI file.
2. Compile to Snowflake: deploy the interface views if you use them, then SYSTEM$CREATE_SEMANTIC_VIEW_FROM_OSSIE_YAML, into a test schema.
3. Test: run the parity queries, with the reference SQL updated to the new definition. Fail the build on any difference.
4. Generate targets: run every converter you depend on. Fail the build on new converter warnings or errors.
5. Publish: deploy the semantic view to production and hand each generated artifact to its tool's own deployment process. Tools that read Snowflake semantic views natively pick up the change without a separate artifact.

No tool keeps a hand-edited copy of the logic, so no tool drifts.

You treated an open OSI model as the source of truth for revenue and compiled it into a Snowflake semantic view, with Cortex Analyst grounded on the same definition. You generated two proprietary formats from the same file and pushed the model through one of them and back. Bound directly to the tables, the conversions lost structure. With an optional interface layer of views, the same round trip kept every relationship and passed every parity test, at the cost of more objects to own. The lesson is architectural, not tool-specific. Own your semantics in one open file, generate and test every proprietary format from it, and decide deliberately how the model binds to the data. Native OSI support across vendors is still maturing, but that architecture is something you can adopt now.