Models and concepts can be exported as Open Semantic Interchange (OSI) documents — YAML or JSON, since JSON is valid YAML — and a document in that shape can be imported back in.

Export is a record of what was certified

Exporting a model or an ontology re-serializes the exact bytes a certifier blessed. It never rebuilds the document from today’s live definitions. If a model has been edited twice since it was last certified, exporting its certified version gives you what the reviewer actually approved, not a preview of the pending edits.
A model’s own page has an OSI document tab showing this same export for its certified version. A concept’s own detail page does not currently offer an export button, and dip has no ontology export command.

Semantic model example

orders.osi.yaml

Ontology example

An ontology exports as an ontology: block. Each concept keeps its own relationships (so a single concept’s document is self-contained), and the block repeats every edge once more at the top level with an explicit from, which is what a reader walking the whole block needs. Bindings ride under a reserved extension key (see the example below), since OSI’s own ontology shape has no dataset mapping of its own.
sales-ontology.osi.yaml
In a document in the exported shape above, fields this platform does not model natively are kept verbatim under extensions rather than dropped, so it survives an export/import round trip unchanged in the parts this platform doesn’t understand. An Open Semantic Interchange semantic model document (datasets: or semantic_model:) is translated rather than kept whole: a dataset’s unmodelled keys are kept in its model’s extensions, but unmodelled keys on the semantic model, a field, a relationship or a metric are not imported, and the import names each one (see how an OSI document becomes models).

Import always lands as a draft

Importing a document — from the Import an Open Semantic Interchange (OSI) document dialog on the models list page, from dip semantic import for a model, or from dip ontology import for an ontology — always creates a draft, regardless of what the document’s own status field says. Certification is a decision made here, by a person, about these specific bytes; it is not a property of a file, and a document cannot import itself as already certified. What the import reports back, rather than applying silently:
  • Every key it does not recognize, kept in the model’s or concept’s extensions rather than dropped, named in a warning like “‑is not a field this platform models; it was kept in extensions and is never interpreted”.
  • Any reference it repaired or any default it applied.
  • For an ontology import, a name collision with an existing concept is refused outright (as already-exists) rather than merged — an import can never silently overwrite a concept that’s already there, certified or otherwise.
Anything the imported definitions violate outright — an unsupported aggregation, a malformed expression (including a derived metric’s), a duplicate name — is refused by name, the same validation a hand-typed definition goes through. An import is not treated as more trustworthy than a person typing the same thing, and arguably less. That includes the time rule for measures: a model import is refused when a measure has no agg_time_dimension and the model has no default_agg_time_dimension, and the message names the model and the measure (see Measures). For a table with no date column, remove the measures before importing and bring the model in as a dimension table.

Accepted shapes

A model import reads the document’s top-level keys to decide which shape it is. version may be a string (such as "0.2.0.dev0") or a number in every shape; it is never interpreted. A document with none of these keys is refused with an error that names the keys it looked for (model, datasets, semantic_model) and the top-level keys it found. A document with more than one of them is refused as ambiguous. One document creates at most 100 models; split a larger one into several documents. The document imports whole or not at all. Every model is checked before anything is written, and all of them are created together: if one dataset is refused, or one model’s name is already taken in the workspace, nothing from the document is created, and the error names the dataset, field or relationship to fix.

How an OSI document becomes models

An OSI semantic model describes several tables; a Dippr semantic model binds exactly one. The translation rules:
  • Each dataset becomes one model, named after the dataset. Its source must be a catalog.schema.table name, which becomes the model’s bound table. A source that is a query, or a name without exactly three parts, is refused naming the dataset: Dippr models bind to one table.
  • Each field becomes a dimension. Its expression is the first of these dialects the field has: TRINO, then ANSI_SQL, then ANSI, then generic SQL; otherwise the first dialect listed. Whenever the chosen expression is not Trino’s, a warning names the dialect used and the fields and metrics that used it. A field is a time dimension when its dimension.is_time is true, or when is_time is unset and its datatype is Date, Time, DateTime or DateTimeTz. A time dimension gets the day grain, so it needs a calendar date: one whose datatype is Date, DateTime or DateTimeTz, or that has no datatype at all, becomes a day-grain time dimension (the first one becomes the model’s default time dimension). A time field of any other datatype — Time (a time of day), or a non-temporal type such as an Integer year marked is_time: true — is imported as a plain dimension, and a warning names it.
  • A field’s datatype becomes its dimension’s column type, so a metric can filter it by value without another step: String becomes varchar, Integer becomes bigint, Decimal becomes decimal, Float becomes double, Boolean becomes boolean, Date becomes date, Time becomes time, DateTime becomes timestamp and DateTimeTz becomes timestamp with time zone. Any other datatype is imported with no column type, and a warning names the field. See Filter values and column types.
  • Each relationship lands on its from dataset’s model, as a many-to-one join to the to dataset’s model on from_columns[0] = to_columns[0]. A relationship whose from or to is not a dataset in the document, whose column lists differ in length, or which joins on more than one column pair, is refused naming the relationship.
  • A metric is imported only when it is one aggregate over one column of one dataset: SUM, COUNT, COUNT(DISTINCT …), AVG, MIN or MAX of dataset.column (or of a bare column, or COUNT(*), when the document has one dataset). It becomes a measure and a simple metric of the same name on that dataset’s model, provided the dataset has a date-bearing field for the measure to aggregate over (the time rule above) — a metric on a dataset without one is skipped and named in a warning rather than refusing the whole document; when the column is one of the dataset’s fields, the measure aggregates that field’s expression. Every other metric — one that spans two datasets, does arithmetic over aggregates, uses a window function, or names a dataset the document does not declare — is skipped and named in a warning with the reason. It is never stored in a form that pretends to be a metric; define it as a ratio or derived metric on the imported models instead.
  • Dataset keys Dippr does not model (such as primary_key, unique_keys, ai_context or custom_extensions on a dataset) are kept in that model’s extensions and named in a warning. A dataset’s ai_context.synonyms also become the model’s synonyms, and a field’s become its dimension’s.
  • Semantic-model-level keys other than version, name, datasets, relationships and metrics (such as description, ai_context or custom_extensions), and the keys of a field, relationship or imported metric that Dippr has no place for (such as a field’s label, a relationship’s custom_extensions or a metric’s datatype, and any member of a field’s dimension or expression object beyond is_time, dialects, dialect and expression) are not imported, and a warning names each one by its path. Only ai_context.synonyms is read from an ai_context; anything else in it (such as instructions), or an ai_context given as plain text, is named in a warning too.
  • Two relationships with the same name on one dataset are refused, naming the relationship and the model.
The import’s warnings, which the CLI prints and the console shows after the import, are:
  • a skipped metric, with the reason;
  • the dialect an expression was taken from, when it was not TRINO;
  • a time field imported as a plain dimension because its datatype has no calendar date;
  • a field whose datatype has no column type equivalent;
  • each key that was kept in extensions, and each key that was not imported;
  • any self-reference that was rewritten to the name the model landed under.
For example, this document creates two drafts, orders (with the relationship and the revenue measure and metric) and customers, and warns that revenue_per_customer was skipped:
shop.osi.yaml
dip semantic import --file shop.osi.yaml prints every created model; with --json the report carries them all under models (and the first under model, as before). The console’s import dialog names every created model and opens the first.

Importing an ontology document

dip ontology import reads an ontology in either of two layouts, told apart by what each entry of the ontology: list is: A document that mixes both kinds of entry is refused, naming the first entry of the other kind. So is a single entry that carries both concept: and concepts:. A Dippr-layout document that declares more than one named ontology is refused too; import each one on its own.

Where the concepts land

Pass --ontology NAME to choose the ontology the concepts are created in. The document’s own name does not override that choice. Without --ontology, the document’s name is used, and that ontology is created if it does not exist. For the OSI layout that is the document’s top-level name, because in the spec the whole document is one ontology.

Property logical types

In Dippr’s own layout, a property’s logical_type is one of boolean, date, integer, number, string, timestamp — the same closed set dip ontology concept create --property NAME=TYPE accepts — matched case-insensitively, so logical_type: STRING and logical_type: string are the same type. Any other value refuses the whole document, naming the concept, the property and the accepted set.

How an OSI spec document is translated

Each EntityType becomes one draft concept. ValueType concepts do not become concepts. Their only job is to give a property its type. Each concept carries its spec entry under the x-osi-concept extension, the value types that typed its properties under x-osi-value-types, and the document’s version and name under x-osi-document. Some text is left out of those copies, because it can name another concept, and extensions are shown as stored to readers who may not see that concept:
  • relationships that became edges. An edge is kept as the edge itself, with one verb phrase. Its other verbalizations and any role name are named in a warning as not imported.
  • rule texts: every requires and derived_by. Each one is named in a warning as not imported.
  • every top-level key other than version, name, ontology and ontology_mappings. The document’s description becomes the ontology’s description when the import creates the ontology. Importing into an existing ontology leaves that ontology’s description unchanged, and a warning says so. Any other top-level key is named in a warning as not imported.

Refused, or imported with a warning

The rule is: if importing without an element would change what a concept means, the whole document is refused. If the element is a rule this platform does not enforce, the concept still means the same thing, so it imports with a warning. Refused. Nothing is written, and the error names the offending elements at once, listing the first 20 and counting the rest:
  • an n-ary relationship, which has more than one role (for example Flight.registers_longitude_series)
  • a relationship to a value type with no multiplicity. That means many values per concept, and a property here holds one value.
  • a multiplicity other than ManyToOne or OneToOne
  • an identify_by entry that names an edge to another concept (for example City identified by its state), names no relationship at all, or is listed twice
  • two relationships with the same name on one concept
  • a relationship to an undeclared concept or to Any, or an edge from a concept to itself
  • a value type with no extends, with a cycle in its extends chain, with supertypes of different datatypes, or with relationships of its own
  • a concept whose type is not EntityType or ValueType, a concept declared twice, or a concept that redeclares a built-in
  • extends on an EntityType. A subtype inherits its supertypes’ relationships, and subtyping is not modelled here, so importing it would create a narrower concept than the document declares.
  • a relationship with roles: null or roles: []. A unary relationship omits roles, and a binary one lists the concept at its other end.
  • a verbalizes that is neither a string nor a list of strings
  • an ai_context.synonyms that is not a list of strings
  • a relationship with a multiplicity but no roles. A unary relationship has neither.
  • a document description that is not a string
  • a document over any size limit:
    • 1 MiB for the whole document
    • 2,000 ontology: entries, counting value types
    • 500 imported concepts (one per EntityType), the same limit a Dippr-layout document has
    • 16 KiB for the document’s version and name, because each concept keeps a copy of them
    • 64 KiB of carried extensions for any one concept, and 4 MiB for all of them together
The OSI spec’s own flights.yaml example is refused on these grounds: it has n-ary relationships, and three concepts are identified through an edge. Imported, with a warning naming the element (the first 100 warnings are listed, and the rest are counted):
  • derived_by and requires, on a concept, a relationship, a value type, or the document. None of them is evaluated or enforced here, and none is imported: the warning is the only record.
  • an edge’s verbalizations after the first, and a name given to its role
  • a key the OSI layout does not define, on a concept, a value type, a relationship or one of its roles. It is kept in extensions, unless it is on a relationship that became an edge, where it is not imported.
  • a top-level key other than version, name, description, ontology and ontology_mappings. It is not imported.
  • a value type that no relationship uses, so nothing was imported for it
  • every entry of ontology_mappings, listed by name with the concepts it maps. Mappings are not imported, for the same reason bindings in a Dippr-layout document are not: tying an imported concept to whichever local model shares a name would claim that your tenant’s table realizes it. Bind each concept to your semantic models in the product.

Round-trip caveats

  • Owner is not part of a model’s document. It is stamped fresh at export time from whoever owns the model today, not preserved from when the version was certified — so re-importing an exported document does not restore the original owner.
  • Created-by, timestamps and certification history never travel. A round trip through export and import always produces a new draft with a new history; it does not resurrect the original model’s audit trail.
  • A concept’s relationships render by name, not by row identity. Renaming a concept changes what its neighbours’ own exports would say about it, even though the underlying relationship never moved — this is a property of the rendering, not a data change, and it is why renaming a concept does not force its neighbours back into review.
  • Ontology import is authoring, gated separately from reading. It only needs concept-authoring rights, not read access to the target ontology namespace — an ontology has no lifecycle of its own to check against.

Ontology concepts

Define business ideas that span more than one dataset.

MCP overview

What Dippr’s MCP server gives an AI agent, and who it acts as.