Skip to main content
What dex accepts from a native Apache Ossie (incubating) document, what it checks, what it makes of what it read, and what it does not claim. Read it beside Native Apache Ossie, which describes how to configure and use the layer, and A native Ossie layer end to end, which runs one document through every command on a local warehouse. This page is the compatibility statement behind both. Every row here is backed by a case in the reviewed corpus at packages/dex-core/tests/ossie/fixtures/, named by its case id. The corpus runs offline against the bundled schema, and an automated test refuses a claim on this page whose case does not exist.

​
The pinned schema

dex vendors the upstream schema verbatim and pins it by content hash. Nothing at runtime needs a checkout of Apache Ossie. The pin is on content and not on the version string, because the schema declares version as a constant that upstream does not move when the schema changes. The same hash appears in the loader, in the bundled exmergo_dex_core/ossie/schema/PROVENANCE.md, in the corpus manifest, and in the table above; an offline test asserts all four agree.

​
Required extras

[ossie] deliberately does not pull [sql]. Structure and integrity decide whether a document is readable at all and are pure plus one validator; expression syntax is a third layer that rides on a dependency a warehouse install already has.

​
What is accepted

​
What is checked, and how hard

Three severities, and they are not three strengths of one verdict. An error means dex could not read the document, which is then absent from the layer. A warning means dex read it and has something to say about what it found. A note means dex read it and is saying what it did not check. Two of those are dex’s own rules rather than upstream’s, marked accordingly in the corpus manifest and worth carrying upstream: cross-file semantic-model uniqueness, and equal arity between a relationship’s two column arrays. The schema constrains both arrays but not their lengths against each other, and a relationship whose sides differ in arity has no complete tuple to join on. What validation proves, and what it does not. There is no external validator here the way dbt parse is for dbt: neither apache-ossie nor apache-ossie-dbt is published, and there is no Ossie runtime to load a document into. A document that passes is schema-valid and internally consistent. That is not a claim that any consumer can execute it, and no dex surface says otherwise.

​
Which expression dex reads

An Ossie field or metric may declare one expression per dialect, and the enum mixes SQL dialects with expression languages that are not SQL. Selection is deterministic:
  1. the active connector’s own Ossie dialect, where the document declares one;
  2. otherwise ANSI_SQL;
  3. otherwise the first supported SQL dialect in declaration order.
Four of dex’s seven connectors (DuckDB, Postgres, Redshift, ClickHouse) have no token in Ossie’s enum. They fall to ANSI_SQL rather than to something close, because a wrong dialect is a worse answer than the portable one. Every declared expression is preserved whichever one dex reads. Cases: dialect_selection, dialect_selection_falls_back_to_portable. MDX, TABLEAU and MAQL are preserved verbatim, never parsed, never a source of a physical column, and never reported as SQL-validated. A bare token in MAQL that looks like a column identifier means something else entirely, so reading one would be worse than reading none. Case: non_sql_dialects_are_metadata. A field resolves to a warehouse column only when both conditions hold: the dataset’s source is a relation this connector can address, and the field’s selected expression is a bare identifier. Everything else carries no column. Case: physical_linkage_is_direct_only, which asserts the resulting link table by equality rather than containment. A link too few costs a screening; a link too many screens the wrong column and reports the verdict as evidence-backed. PII linkage follows exactly this table. A dimension dex cannot resolve to a column is screened by the name heuristic and says so, rather than being screened against a column that is not behind it. The policy that linkage feeds is in �0.

​
Keys, relationships, snapshots, and authoring

adversarial_composite is the case worth reading. Its child tuples are (1, 10, 100) and (2, 20, 200), its parent tuples (1, 20, 200) and (2, 10, 100). Every column overlaps independently, so a probe that measures one column at a time reports a healthy join three times over; no complete tuple matches, so the join finds nothing. The two sides are named differently so that copying one side’s columns onto the other cannot pass.

​
What Ossie does not carry, declared rather than absent

These are properties of the format, not of how far the implementation got, and they arrive in the catalog’s unavailable block rather than as empty fields a caller would read as facts about the layer. Ossie is a semantic layer and never a transformation project. project.format: ossie is refused rather than translated, and the reader satisfies none of the project tiers: it owns no model graph, no compilation, no targets, and no dbt write surface. A repository may have dbt beside Ossie, Ossie alone, or dbt alone.

​
What dex does not claim

  • No converter interoperability. dex reads Ossie documents; it does not convert them to or from another semantic format, and says nothing about what another tool would make of one.
  • No execution assurance. A document that validates here is schema-valid and internally consistent. Whether any engine can execute it is a separate question dex has no basis to answer.
  • Missing SQL validation is disclosed, not passed. Without [sql] the expression layer does not run and the document says so. That note is the absence of a check, not a check that succeeded.
  • A warning is not a partial refusal. A document that warns is read in full.

​
Known deltas from upstream’s current schema

Upstream moves; the pin does not, until somebody moves it deliberately.

​
Upgrading the pin

  1. Copy the new core-spec/ossie-schema.json in verbatim.
  2. Update the commit, hash, and declared version in PROVENANCE.md, in SCHEMA_SHA256 in exmergo_dex_core/ossie/loader.py, in the corpus manifest’s schema: block, and in the table on this page.
  3. Run the corpus. Read every case whose verdict moved, decide for each one whether the new verdict is what upstream now intends, and record it in the changelog with the behavior it changes.
  4. Update the tables on this page for anything that moved, and re-check the known-deltas list: a delta upstream has adopted stops being a delta.
Updating the hash alone is not an upgrade. The offline test checks that the four places agree with each other; it cannot check that anybody read the diff, and it should not be quoted as though it did. Source: references/ossie-compatibility.md (edit on main). This page is generated; change the source, not the site.