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, ordosi_engine.DATUS_EXT_VERSION. - Scope: semantics that Apache Ossie (formerly
OSI) core spec
0.3.0.dev0cannot yet express, carried inside the Ossie-sanctionednonportable_extensionsfield 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 fullagent.ymlcan be passed as--connectionsdirectly — 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 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:
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 lowercasedatuskeeps working.data: a JSON object containing the vendor payload. At most oneDATUSentry per object. Two envelope keys are reserved:vandrequires.
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 butDATUS, compared case-insensitively) is ignored. - A malformed
DATUSoption (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.10and1.1are the samef64, 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¶
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):
- the metric's own
time_dimension(highest precedence); - else the unique primary time among the metric's datasets (explicit dataset
time_dimension, else the single-is_timeinference).
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):
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 theTHEN/ELSEvalues 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:
- where a filter applies, and how a fixed time key keeps its storage grain
- reading a fixed value next to detail rows
- why the core expression must match the declaration
includeandexcludemetrics, andfixedon a metric- aligning two facts on one axis
- a value from another dataset's rows
- which combinations need separate queries
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_extensionsis valid Ossie, so a model carrying Datus extensions still passes it. - Datus self-validation (engine in
--osi-datusmode, the default, when it reads aDATUSentry): the payload must be a JSON object; known keys must match their declared type/enum; otherwiseinvalid_datus_extension. Unknown keys pass (forward-compat) unless named inrequires. The envelope version gate (above) runs here, once per payload — including on theSemanticModelcarrier, which defines no keys of its own but is still held to the envelope. - Basic mode (
--osi-basic): the engine treatsDATUSlike any unknown vendor — the extension is inert (spec-compliant passthrough) and the compile collects oneignored_vendor_extensionwarning 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_timeinference 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 anaggregate_field_droppedwarning and any metric or query referencing it fails closed withunknown_field/unknown_column. The alternative would beAVG(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_timeprimary-time inference is not an extension — it applies in basic mode too, sometric_timestill 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.