Skip to content

Datus extensions to Apache Ossie

  • Status: draft, in use by Datus (dosi-engine + the Datus generation agent).
  • Spec version: datus-ext/1 (the major series)
  • Current version: 1.14 — see Extension versions for what each minor added and how a version bump is decided. Any engine can report the version it implements: dosi info, GET /v1/capabilities, or dosi_engine.DATUS_EXT_VERSION.
  • Scope: semantics that Apache Ossie (formerly OSI) core spec 0.3.0.dev0 cannot yet express, carried inside the Ossie-sanctioned nonportable_extensions field so a document stays fully Ossie-valid and every non-Datus consumer ignores them.

This page is the overview: what each extension controls, how an extension is written, and the full contract of the simple ones. The larger extensions — window metrics, levels of detail, parameters, derived metrics, cross-fact alignment, time storage formats — each have a page of their own, listed under Larger extensions.

Separately from model semantics, dosi-engine's connection configuration also speaks Datus: profiles use the agent.yml datasources: vocabulary and a full agent.yml can be passed as --connections directly — see connectors.md.

This is a private vendor extension: it does not need to be accepted by the Ossie working group to be usable. Where an extension generalizes a gap that belongs in the core spec (time granularity, cumulative windows), the long-term home is an Ossie RFC; this document is the interim vehicle Datus ships against today.

What each extension does

Every extension is optional. Add one only where you want to change the default; a model without any behaves exactly as pure Ossie says it should.

Extension Carrier Key What it controls Default when absent
D-JOIN Relationship join_type keep or drop fact rows with no match when a join reaches a dimension left — orphan rows are kept
D-FILL Metric fill_nulls_with the number a group with no rows shows a bare count fills 0, anything else NULL
D-TIME Dataset / Metric time_dimension which time column is the business time axis (metric_time) the dataset's single is_time field, else none
D-GRAIN time Field time_granularity the grain a column is stored at inferred from the type or format, otherwise any grain
D-DATASET Metric dataset the home dataset of a COUNT(*) derived from the SQL, else count_star_needs_dataset
D-DIM Field is_dimension whether a field is offered as a dimension inferred from keys, relationships and aggregated columns
D-DETERMINES Field determines the fields each value of a field has one value of, so a distinct count of it splits by them keys, many-to-one relationships and fixed fields
D-MEASURE Metric measure the name of the metric's measure generated from the aggregate
D-WINDOW Metric window period-over-period, rolling, cumulative, rank and value windows the plain base aggregate
D-LOD Field / Metric lod, derive type lod calculate at one grain, display at another a field is a stored column
D-PARAM Metric / Field params window widths and filter literals bound at query time every slot is the literal it declares
D-DERIVE Metric derive a metric built from other metrics (filter, compose) a self-contained metric
D-CONFORM Relationship cardinality align two facts on a shared dimension without joining them many_to_one — the edge is a join
D-FORMAT time Field time how a time column stores dates (20260907, 202609) a native DATE / TIMESTAMP is assumed

dosi info lists every key the engine reads, with the version that introduced it and what ignoring it costs.

Why your model stays valid Ossie

Ossie's schema is strict (additionalProperties: false everywhere), so we cannot add bare fields like relationship.join_type. But the spec provides a first-class escape hatch on every major object:

nonportable_extensions:
  - vendor_name: <string>
    data: <JSON object>

nonportable_extensions is present on SemanticModel, Dataset, Field, Relationship, and Metric. The upstream ossie validator accepts it, so a document carrying Datus extensions passes upstream validation unchanged. A consumer that doesn't understand vendor_name: DATUS simply skips it — the model still means exactly what pure Ossie says it means. The Datus extensions only refine engine behavior at points Ossie leaves undefined; they never change what a metric or dimension is.

Writing an extension

A Datus extension is one nonportable_extensions entry:

nonportable_extensions:
  - vendor_name: DATUS
    data: {"v": "1.1", "<option>": <value>}
  • vendor_name: canonically the uppercase constant "DATUS" (matching the Ossie spec's uppercase enum style, e.g. ANSI_SQL). Matching is case-insensitive; the historical lowercase datus keeps working.
  • data: a JSON object containing the vendor payload. At most one DATUS entry per object. Two envelope keys are reserved: v and requires.

Consumption rules (dosi-engine):

  • Absent → the documented Ossie default (overview). Extensions are purely additive; a model with none behaves exactly as today.
  • Unknown payload keys are ignored, not rejected — so a newer Datus agent can emit keys an older engine doesn't read without breaking it (forward-compat). The exception is requires, below.
  • Unknown vendor_name (anything but DATUS, compared case-insensitively) is ignored.
  • A malformed DATUS option (such as a known key with the wrong type) is a structured error (invalid_datus_extension), not a silent default — a Datus-authored document is held to the Datus contract. Compilation still continues with the default, so one pass reports every problem in the model.

v — the declared version

v is MAJOR.MINOR. The string form is canonical ("v": "1.1"); a JSON number is accepted for convenience ("v": 1.1, and the bare integer "v": 1 meaning 1.0).

A JSON number can only carry minors 0–9. 1.10 and 1.1 are the same f64, so a number cannot express minor 10; a number with two or more fractional digits is rejected outright with a message telling you to use the string form. Once the current minor reaches 10, write "v" as a string always.

v is optional and omitting it is always safe — an unversioned payload behaves exactly as it did before the version gate existed, and produces no diagnostic. The version is declared per nonportable_extensions entry, not per document: a model-level v does not become a default for its datasets, fields, relationships, or metrics.

What stamping a version buys you, given the engine's own version:

Situation Engine's response Code
v absent or null silent — behaves as before the gate —
v malformed (bad string, wrong JSON type, number with ≥2 decimals) error invalid_datus_extension
v below 1.0, or a major newer than the engine's error unsupported_datus_ext_version
minor newer than the engine's warning naming the keys that were dropped; everything the engine knows still applies datus_ext_version_ahead
a key newer than the v you declared warning; the key is honored anyway datus_ext_key_newer_than_declared
minor older than the engine's, keys all within it silent —

A future major is the one blanket rejection: a major bump means at least one key changed meaning, and an engine that predates the change has no way to know which — reading the payload anyway would produce quietly wrong numbers. Minors are additive by construction, so they only ever warn.

requires — keys that must not be dropped

data: {"v": "1.4", "requires": ["semi_additive"], "semi_additive": {"reduce": "last"}}

requires is an array of key names the producer declares must not be silently ignored. A consumer that does not implement a listed key raises datus_ext_key_required naming it, instead of dropping it.

This exists because a consumer cannot judge the danger of a key it has never heard of. "Unknown keys are ignored" is the right default for a key like join_type, where ignoring it falls back to a documented behavior — but the wrong default for a key like semi_additive, where ignoring it means summing an end-of-period balance and returning a number that is simply wrong. The producer knows which is which; requires is how it says so.

Emit requires for every key whose ignore-impact is silent (see the versioning policy) and for nothing else: letting an older engine degrade is better than refusing to serve it. dosi info / GET /v1/capabilities report each key's impact.

In Datus mode, a non-null silent key omitted from requires emits datus_ext_requires_missing, even when v is absent. The model still compiles; add the named key to requires to protect older consumers.

When a version is bumped, what each minor added, and which keys are still to come are recorded on Extension versions: the versioning policy, the change log and the roadmap.

Simple extensions

Each of these is one key with a small value, and its whole contract fits in its section.

D-JOIN — relationship join type

Where: a Relationship's nonportable_extensions. Payload key: join_type, enum "left" | "inner". Default (absent): "left".

Say you measure revenue on line_items and want it broken down by orders.status. Some line items point to an order that isn't in your orders table — a late-arriving row, a soft-deleted order, a data-quality gap. join_type decides what happens to their revenue when a fan-out branch follows this relationship (many→one) to join the "one" side in, reaching a dimension or an off-base measure:

  • "left" (default): keep rows on the many side that have no match — orphan fact rows survive and land in the NULL group of any dimension drawn from the missing side. Reconciliation / audit semantics: every dollar is accounted for.
  • "inner": drop unmatched many-side rows. Attribution semantics — a measure is only counted where the entity it attributes to actually exists.
relationships:
  - name: line_items_to_orders
    from: line_items
    to: orders
    from_columns: [order_id]
    to_columns: [order_id]
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.0", "join_type": "inner"}

Same query, orphan revenue of 50:

join_type status revenue
left (default) paid 300
(blank) 50 ← orphans kept
inner paid 300
(orphan row dropped)

This makes the INNER-vs-LEFT choice an explicit property of the relationship instead of a hard-coded generator default (S-JOIN in the semantics contract), so every query that follows the join gets the same answer. dosi query --explain shows each join's kind, so you can confirm the extension took effect.

D-FILL — metric null-fill for missing merge groups

Where: a Metric's nonportable_extensions. Payload key: fill_nulls_with, a JSON number. Default (absent): engine default — a bare COUNT metric fills 0 (S-FAN-6 in the semantics contract); every other metric keeps NULL.

You ask for order_count and signups by city, and a city had signups but no orders this period. After the multi-branch merge, a group present in only some branches projects NULL for the metrics evaluated in the missing branch. A plain count already reads 0 there — a count of nothing is zero — but a SUM stays blank, because "the sum of no rows" could mean 0 or unknown. fill_nulls_with: <n> decides per metric: it COALESCEs this metric's output to <n> (typically 0) in both merge and single-branch plans, for any metric kind (SUM, ratio, expression), and takes precedence over the count default.

metrics:
  - name: revenue
    expression:
      sql: SUM(orders.amount)
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.0", "fill_nulls_with": 0}

revenue and signups by city, where Denver has signups but no orders:

city revenue (default) revenue (fill_nulls_with: 0)
Austin 900 900
Denver (blank) 0

The declared fill is part of the metric's value, wherever it is read: as its own column, as a member of a compose (inlined or read after a window stage), and as the series a window.base ranks, totals or shifts. A metric ranked or averaged over its fill reads the same number it shows on its own. Where a divisor reads a filled member, the engine wraps the whole divisor in NULLIF(…, 0): the member alone, an expression over it such as y * 2, a compose that reads it, or a window over it, which reads it filled. A filled 0 then divides into NULL, as the unfilled NULL did. A window metric's own fill is not applied where another metric reads it, nor to its own output.

The count default (S-FAN-6) is narrower: it is applied only to the metric's output, never to a measure embedded in a ratio/expression — a count denominator must not become a literal 0 divisor. Under a window stage the merged measure column stays NULL, and the count default is applied where the bare count metric is projected as an output. A count without a declared fill that a compose or ratio reads as a member — or that sits inside a window.base series — keeps NULL. Adding a window metric to a query never moves a selected count from 0 to NULL.

D-TIME — primary (aggregation) time dimension

Where: a Dataset's or a Metric's nonportable_extensions. Payload key: time_dimension, a string name reference — on a dataset, the name of one of its own is_time fields; on a metric, "field" or "dataset.field". Default (absent): a dataset with exactly one is_time field gets it as implicit primary time (this inference reads no extension, so it applies in basic mode too); zero or several is_time fields → no primary time.

A query says "revenue and inventory moves, by month, last quarter" — but which column is time? orders has order_date and ship_date; the inventory table has move_date. time_dimension declares which time column is a table's or a metric's business time axis — the column the engine uses when a query asks for a time range or grain without naming a column. Resolution per metric (S-TIME-5):

  1. the metric's own time_dimension (highest precedence);
  2. else the unique primary time among the metric's datasets (explicit dataset time_dimension, else the single-is_time inference).

A metric-level bare "field" resolves against the metric's own datasets first (time-field names like etl_dt recur across datasets), widening to the whole model only if none of them has the field.

datasets:
  - name: orders
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "time_dimension": "order_date"}
    fields:
      - name: order_date
        dimension: { is_time: true }
      - name: ship_date
        dimension: { is_time: true }
metrics:
  - name: shipped_revenue          # same SUM, but on the shipping axis
    expression:
      sql: SUM(orders.amount)
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "time_dimension": "ship_date"}

Queries consume this through the reserved name metric_time (--group-by metric_time:month, --time-dimension metric_time):

dosi query --metrics revenue,moves --group-by metric_time:month

Each metric is truncated on its own table's primary time column and the results align on the shared metric_time__month output. A time range with no named dimension and no time item in the group-by filters each metric's primary time — per aggregation branch, on that branch's own column. A metric with no resolvable primary time yields no_primary_time_dimension. Metrics on one base with different primary times are not an error: each time axis gets its own branch over that base, and the branches merge on the group keys, so each metric returns what it returns alone.

The reference must exist and have an effective is_time: true (explicit or from the core datatype default), else invalid_datus_extension.

D-GRAIN — native time granularity

Where: a Field's nonportable_extensions (the field must be dimension.is_time: true, explicitly or from the core datatype default). Payload key: time_granularity, enum "day" | "week" | "month" | "quarter" | "year". Default (absent): inferred from time.format or core datatype: Date (day); otherwise unknown — any query-time grain may be requested.

Declares the grain the column is stored at (a monthly snapshot's etl_dt, say). Requesting a strictly finer grain (:day on a month column, via an explicit group-by item or via metric_time) is a structured grain_too_fine error instead of silently wrong data. Truncation to the native grain or coarser is unchanged. Interim vehicle for the upstream RFC's dimension.time.granularity. A column that stores dates as strings or integers declares its grain together with its layout — see D-FORMAT.

fields:
  - name: etl_dt
    dimension: { is_time: true }
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "time_granularity": "month"}

D-DATASET — metric home dataset

Where: a Metric's nonportable_extensions. Payload key: dataset, a string naming a dataset of the model. Default (absent): attribution is derived from the metric SQL alone.

A COUNT(*) names no column, so in a multi-dataset model with no other aggregate pinning a dataset, Ossie leaves its attribution undefined and the engine errors (count_star_needs_dataset). The hint resolves exactly that tie. It never overrides SQL-derived attribution — a metric whose aggregates name columns keeps their datasets regardless of the hint (extensions never redefine what the SQL says). An unknown dataset name is invalid_datus_extension.

metrics:
  - name: chat_message_count
    expression:
      sql: "COUNT(*)"
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.1", "dataset": "chat_record"}

D-DIM — which fields are offered as dimensions

Where: a Field's nonportable_extensions. Payload key: is_dimension, a boolean. Default (absent): the engine infers the field's role (see below).

Ossie types every non-time field as a regular dimension, so a model cannot say that a column is a measurement (unit_cost), an identifier (c_customer_id), free text, or PII. Grouping by such a column is not a structural error — the SQL runs, the numbers are right, and the analysis is meaningless. is_dimension is how the model says so once, at modelling time, instead of every caller re-deciding it at every call.

It is a listing signal, not a permission:

Written Effect
absent the engine infers (below)
false the field is not recommended: list_dimensions marks it is_dimension: false, and attribution does not offer it as a candidate. Naming it in group_by still works.
true the field is recommended even where inference would exclude it — the way to group a numeric column into buckets

Because it never reaches the planner, ignoring the key changes no number; it only costs a caller a worse shortlist (documented impact).

datasets:
  - name: store_sales
    fields:
      - name: ss_quantity            # a measurement no metric aggregates
        expression: { sql: ss_quantity }
        nonportable_extensions:
          - vendor_name: DATUS
            data: {"v": "1.7", "is_dimension": false}
      - name: i_current_price        # numeric, but analyzed in price bands
        expression: { sql: i_current_price }
        nonportable_extensions:
          - vendor_name: DATUS
            data: {"v": "1.7", "is_dimension": true}

Inference when the key is absent. The engine uses only model structure — it never probes the warehouse (a COUNT(DISTINCT …) on a high-cardinality column is not a cost the engine may impose). A field is not offered when it is a primary-key member, a single-column unique key of the metric's own home dataset, a column named in a many-to-one relationship's join pair (a D-CONFORM pairing is not a join; its columns are the dimension itself), or a column some metric measures — the value read by a SUM/AVG/STDDEV*/VAR*. Everything else is offered, and list_dimensions reports which rule applied, as source.

Three aggregates that mention a column without measuring it, and therefore leave it a dimension:

  • COUNT — COUNT(DISTINCT region) ("how many active regions") is an ordinary metric over an ordinary dimension. This holds for the metric being listed too: the answer for a field does not depend on which metric you ask about.
  • MIN / MAX — they order strings and dates perfectly well; MIN(activity_code) picks one identifier, it does not measure it.
  • A condition inside an aggregate — SUM(CASE WHEN is_instant THEN 1 ELSE 0 END) counts rows where a flag holds; the flag stays a dimension. Only the THEN/ELSE values are measured. A D-DERIVE filter folds into exactly this shape, so it behaves the same way.

Inference cannot see a business key that is neither a declared key nor a relationship column, a numeric column no metric reads, free text, or PII — those are exactly the fields worth declaring.

D-DETERMINES — fields one field determines

Where: a Field's nonportable_extensions. Payload key: determines, a non-empty array of names of other fields of the same dataset. Default (absent): what the model already says — keys, many-to-one relationships and fixed fields.

determines says that each value of the field has exactly one value of each listed field, on every row the dataset reads. It matters for a COUNT(DISTINCT …) of the field: no value is then counted in two groups of a listed field, the groups' distinct counts add up to the whole, and attribute_dimensions can split the count by that field.

The model already says it in most cases, with nothing to declare: a primary or unique key determines every field of its dataset; a field that leaves by a many-to-one relationship determines every field of the dataset it leads to, and of the datasets beyond (along the path a query joins by — with two paths to a dataset, neither counts); a relationship's column is determined wherever its pair is, since on a row the join matched the two are equal. A fixed field is the exception: a time range restricts a fixed calculation too, so a user's order count can be 1 in one compared period and 2 in the other. It is determined by its own keys, and by a key or a relationship that leads to them, only where no period can move its value: the period does not land on its base's rows, or its keys decide the time field it lands on — the default one, or the one a request names in baseline.dimension — and the count is cut on that field too (a user counted by the day their orders are placed, in a period none of them is delivered in, would read a delivered count over none of them). Which day an order is on is no proof for its user's count: the user's other orders are on other days, and two periods may overlap. A field that reads a fixed one, an alias or a bucket of it, is determined where everything it reads is: the fixed field and each column. A name in a field expression is the stored column, so a column is determined where its row is, or where a determined field reads it unchanged; a field of the same name that transforms it does not count. A declaration chains with them. The declaration is for a field copied onto the rows of a fact with no dimension table behind it — an engineer's region on each work order:

datasets:
  - name: work_orders
    fields:
      - name: engineer_id
        expression: { sql: engineer_id }
        nonportable_extensions:
          - vendor_name: DATUS
            data: {"v": "1.14", "is_dimension": false, "determines": ["region", "city"]}

It is a declaration: the engine trusts it and reads no data to check it. It must hold at any time on every row a period can read: every row with a value on the time field of the metrics that count the field (here d) — an engineer who changed region once breaks it. A row with no value there is in no period. A NULL counts as a value, of the field and of each listed one: declarations chain, so the rows where the field itself is NULL must agree too. Check the data before declaring: for each listed field, this returns no rows.

SELECT engineer_id
FROM work_orders
WHERE d IS NOT NULL
GROUP BY engineer_id
HAVING COUNT(DISTINCT region) + MAX(CASE WHEN region IS NULL THEN 1 ELSE 0 END) > 1
LIMIT 5

The data shows only the rows there are now. Whether it keeps holding as rows come is a business rule, for whoever owns the model to confirm.

A split whose data breaks it within a period is refused, not computed: over its groups the count is larger than over everything, and the call reports dimension_not_aligned. So is a split by a relationship's column that some rows do not match, where a value is counted both in the NULL group and in another: a store in an area that is a market in one month of the period and not in another. Where the relationship also joins on a field the counted one does not decide (the month beside the store), the store can as well be in the NULL group in one compared period and in its area in the other, which neither period shows on its own: a split by such a field is refused whenever it has a NULL group in either period. Split by the field it is joined on instead, or keep the matched rows with context_filter. Past such a relationship only a field that reads a column as it is counts as determined: one computed over it, COALESCE(area, 'unknown'), turns the unmatched rows' NULL into a group of its own, and a split by it is refused before anything is fetched. A value that moves between the two compared periods, an engineer in one region in July and another in August, is not caught: a split of a ratio or a rank by the field then counts it twice. Queries never read the declaration, so it changes no number a query returns. dosi validate reports a listed field the model already implies as redundant_determines; never a fixed one, which a request on another time field may need declared. Ignoring the key leaves those metrics refused by attribute_dimensions (degraded impact).

D-MEASURE — explicit measure name

Where: a Metric's nonportable_extensions. Payload key: measure, {"name": <identifier>}. Default (absent): the sanitizer-generated stem (S-MEASURE-1).

Names the metric's single synthesized measure explicitly. Measure names are otherwise derived from the aggregate argument (S-MEASURE-1): letters and digits of any script stay, so CASE literals such as the Greek 'νέο' / 'παλιό' ("new" / "old") keep the two names apart, and aggregates that differ only in an operator get a signature tag (…_sum_1f3a9c0e, S-MEASURE-2). Such names can be long and are quoted in the generated SQL when they are not plain ASCII; an explicit name gives the measure a short one. The explicit name is a label: dedup still keys on the aggregate signature (an undeclared textual twin shares the declared name), the name enters the same collision checks (two explicit names on one signature, or one name on two signatures, still collide loudly), and it applies only to single-aggregate metrics. Because measure names surface in result columns and metadata, ignoring this key silently renames them — emit it under requires so older engines refuse instead (the first silent-impact key since requires shipped).

metrics:
  - name: new_product_revenue
    expression:
      sql: "SUM(CASE WHEN orders.category = 'νέο' THEN orders.amount END)"
    nonportable_extensions:
      - vendor_name: DATUS
        data: {"v": "1.4", "requires": ["measure"], "measure": {"name": "orders_new_product_amount_sum"}}

measure, like derive, is normally written by the modeling tool rather than by hand.

Larger extensions

These change what a metric or a field computes, or how two tables meet, and each is specified on a page of its own. The sections below say what each one is for and where to read on.

D-WINDOW — window metrics

The window key on a metric declares period-over-period comparison, rolling and cumulative aggregates, ranks and first/last/nth values over the metric's own aggregate, without raw window SQL in the expression (which the engine rejects as window_in_metric). The time axis comes from D-TIME. Start with the quick start; the rest of Window metrics is the full specification.

D-LOD — levels of detail

A field carries lod: {expr: ...}, a metric carries derive: {type: "lod", expr: ...}: group the records one way, then use the result in a query grouped another way — Tableau's FIXED, INCLUDE and EXCLUDE. Understand LOD explains the idea and runs a first model, the commerce walkthrough builds a complete one, and the authoring reference has every rule:

D-PARAM — query-time parameters

The params key turns a window width, an offset count, a rank bucket count or a literal in a filter into a typed parameter the query binds: one moving_avg(n) instead of r7_revenue / r30_revenue / r90_revenue. A multiple parameter takes a set of values, the whole value list of an IN (color IN (:colors)), so a multi-select is one parameter rather than a fixed number of slots. Parameters fill typed holes only, never SQL text. Parameterized metrics is the specification, including multi-select parameters, a field's own parameters, a level-of-detail field's base and a derived subtype's thresholds.

D-DERIVE — derived metrics

The derive key records how a metric derives from other metrics of the same model: a filter variant of a base metric, a compose of several, or a window over another metric's series. The engine checks that the metric's expression matches the declaration, and exposes the structure to dosi list, lineage and attribution. It is normally written by the modeling tool. See Derived metrics.

D-CONFORM — conformed relationships between facts

cardinality: many_to_many on a relationship pairs two fact tables on the dimensions they share — a date, a platform — without joining their rows: each fact aggregates alone and the results merge. Its impact if ignored is silent, so list it in requires. See Cross-fact alignment.

D-FORMAT — time storage format

The time key on a time field declares how dates are stored when the column is not a native date — '20260907', 202609, '2026年09月07日' — so the engine can group the column by month or year and still filter it with partition-friendly bare comparisons. Its impact if ignored is silent, so list it in requires. Time storage format covers when to configure it, a quick start, writing filters, the supported formats, grouping and range boundaries, validation and known limits and the SQL it produces.

Validation & engine modes

  • Upstream Ossie validation (dosi validate --osi-basic, see the CLI reference): unaffected — nonportable_extensions is valid Ossie, so a model carrying Datus extensions still passes it.
  • Datus self-validation (engine in --osi-datus mode, the default, when it reads a DATUS entry): the payload must be a JSON object; known keys must match their declared type/enum; otherwise invalid_datus_extension. Unknown keys pass (forward-compat) unless named in requires. The envelope version gate (above) runs here, once per payload — including on the SemanticModel carrier, which defines no keys of its own but is still held to the envelope.
  • Basic mode (--osi-basic): the engine treats DATUS like any unknown vendor — the extension is inert (spec-compliant passthrough) and the compile collects one ignored_vendor_extension warning per carrying element — SemanticModel, Dataset, Field, Relationship, and Metric alike — naming the default that applies instead (D-JOIN → LEFT, D-FILL → no fill beyond S-FAN-6, D-TIME → single-is_time inference only, D-GRAIN → any grain, D-DATASET → SQL-derived attribution only, D-WINDOW → the plain base aggregate, D-FORMAT → the column is assumed to be a native date, which for a string or integer column means a warehouse type error or silently wrong rows, D-LOD → the field is dropped, D-CONFORM → the edge is an ordinary many→one join, so the two facts are joined row to row and duplicate-sensitive aggregates across it fan out). D-LOD is the one that cannot degrade to a value: without the declaration the field's expression is a bare aggregate, which is not a legal row-level attribute, so the field is dropped with an aggregate_field_dropped warning and any metric or query referencing it fails closed with unknown_field / unknown_column. The alternative would be AVG(COUNT(DISTINCT …)) reaching the warehouse. The payload is not parsed, so a malformed payload is also just ignored-with-warning — and no version diagnostic can occur in basic mode at all. The same model file is valid in both modes; only the semantics differ. (The single-is_time primary-time inference is not an extension — it applies in basic mode too, so metric_time still works wherever pure Ossie determines a unique time axis.)

Non-goals / boundaries

  • Datus extensions never redefine an Ossie object's identity or a metric's SQL — only engine behavior at Ossie-undefined seams.
  • They are not a place to smuggle vendor SQL. Metric expressions stay Ossie expression.dialects; the engine still infers metric semantics from that SQL.
  • Semantics that belong in Ossie core (granularity, time spine, window/cumulative metrics) may eventually be standardized upstream; if/when adopted there, the corresponding Datus extension (D-GRAIN, D-WINDOW) is retired in favor of the core field.