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 anontology: 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, fromdip 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.
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
sourcemust be acatalog.schema.tablename, 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, thenANSI_SQL, thenANSI, then genericSQL; 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 itsdimension.is_timeis true, or whenis_timeis unset and itsdatatypeisDate,Time,DateTimeorDateTimeTz. A time dimension gets thedaygrain, so it needs a calendar date: one whosedatatypeisDate,DateTimeorDateTimeTz, or that has nodatatypeat all, becomes a day-grain time dimension (the first one becomes the model’s default time dimension). A time field of any otherdatatype—Time(a time of day), or a non-temporal type such as anIntegeryear markedis_time: true— is imported as a plain dimension, and a warning names it. - A field’s
datatypebecomes its dimension’s column type, so a metric can filter it by value without another step:Stringbecomesvarchar,Integerbecomesbigint,Decimalbecomesdecimal,Floatbecomesdouble,Booleanbecomesboolean,Datebecomesdate,Timebecomestime,DateTimebecomestimestampandDateTimeTzbecomestimestamp with time zone. Any otherdatatypeis imported with no column type, and a warning names the field. See Filter values and column types. - Each relationship lands on its
fromdataset’s model, as a many-to-one join to thetodataset’s model onfrom_columns[0]=to_columns[0]. A relationship whosefromortois 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,MINorMAXofdataset.column(or of a bare column, orCOUNT(*), 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_contextorcustom_extensionson a dataset) are kept in that model’s extensions and named in a warning. A dataset’sai_context.synonymsalso become the model’s synonyms, and a field’s become its dimension’s. - Semantic-model-level keys other than
version,name,datasets,relationshipsandmetrics(such asdescription,ai_contextorcustom_extensions), and the keys of a field, relationship or imported metric that Dippr has no place for (such as a field’slabel, a relationship’scustom_extensionsor a metric’sdatatype, and any member of a field’sdimensionorexpressionobject beyondis_time,dialects,dialectandexpression) are not imported, and a warning names each one by its path. Onlyai_context.synonymsis read from anai_context; anything else in it (such asinstructions), or anai_contextgiven 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.
- 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
datatypehas no calendar date; - a field whose
datatypehas 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.
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’slogical_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
EachEntityType 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
requiresandderived_by. Each one is named in a warning as not imported. - every top-level key other than
version,name,ontologyandontology_mappings. The document’sdescriptionbecomes 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
ManyToOneorOneToOne - an
identify_byentry that names an edge to another concept (for exampleCityidentified by itsstate), 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 itsextendschain, with supertypes of different datatypes, or with relationships of its own - a concept whose
typeis notEntityTypeorValueType, a concept declared twice, or a concept that redeclares a built-in extendson anEntityType. 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: nullorroles: []. A unary relationship omitsroles, and a binary one lists the concept at its other end. - a
verbalizesthat is neither a string nor a list of strings - an
ai_context.synonymsthat is not a list of strings - a relationship with a
multiplicitybut noroles. A unary relationship has neither. - a document
descriptionthat 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
versionandname, 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
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_byandrequires, 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,ontologyandontology_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.
Related
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.