OSI (Ossie) and Semantic Hub mapping

This guide explains the authoring format and semantics. Target support varies; see Support and limitations.

This document describes how Semantic Hub's canonical model and GENERIC expression language relate to the Open Semantic Interchange (OSI) expression-language proposal maintained in the Apache Ossie repository. It is an interoperability guide, not an extension of the JSON Schemas. Metrics.json remains limited to validating Semantic Hub model instances.

The upstream reference is the Ossie Proposal: Expression Language, whose status was Proposed Final when this mapping was reviewed on August 19, 2026. Because that proposal can evolve, an implementation claiming OSI compatibility must record the OSI version or commit it implements.

1. Dialect relationship

OSI (Ossie)	Semantic Hub	Mapping
`OSSIE_SQL_2026`	`GENERIC`	Both are portable, SQL-based logical-layer languages. Semantic Hub imports supported OSI syntax into canonical expressions and structural metric properties. They are related dialects, not aliases: conformance must be checked feature by feature.
Vendor dialect extension	`dialect_expressions`	Field-level target-specific export text. Metric target-specific text is allowed only in `MetricOverride.dialect_expressions` as a documented last resort.
Imported vendor expression	`imported_expression`	Preserves the original third-party dialect and text for history and future forward-engineering; it is not the canonical definition used for Semantic Hub semantics.

Semantic Hub serializers should emit a standard SQL spelling when a canonical function has one. Parsers may accept the aliases in this document but must normalize them before dependency, lineage, grain, caching, or target-capability analysis.

Planned scalar parity

Requirements accepted on 2026-10-23 cover casts, date/time operations, string functions and numeric functions from Ossie's required language catalog. See the planned scalar expansion for the function families, examples and selected semantic profile. The current upstream dialect spelling is OSSIE_SQL_2026. The parser, shared type checker and target-specific compiler lowering implement this phase with explicit overload limitations. This does not establish full Ossie conformance or live verification on every target.

2. Expression-context mapping

OSI defines one logical-layer SQL expression subset for fields, metrics, and filters. Semantic Hub uses that syntax in three explicit contracts so validators and SDKs know the evaluation phase and expected result:

Semantic Hub contract	OSI role	Additional Semantic Hub rule
`RowExpression`	Scalar field or column expression	Evaluates before aggregation and may bind only row-level dependencies reachable from the anchor dataset.
`AggregationExpression`	Metric expression, including aggregate calls	Evaluates at the aggregation phase. A raw row dependency is legal only inside an explicit aggregate call.
`FilterExpression`	Filter expression	Uses row-expression binding rules and must type-check to Boolean. Query-level post-aggregation filters are validated separately.

Both languages support SQL identifiers, qualified references, arithmetic, comparisons, Boolean operators, null tests, IN, BETWEEN, pattern matching, scalar functions, aggregate functions, and CASE. Semantic Hub adds catalog-aware binding rules for source columns, model fields, metric namespaces, dataset relationship paths, evaluation grain, and fanout safety. Those rules are defined in Object naming, Expression language, and YAML model validation requirements.

Semantic Hub DIVIDE(numerator, denominator[, alternate]) is a GENERIC extension for portable operator-local zero-denominator handling. When exporting it to OSI, a compiler lowers it to a semantically equivalent CASE, NULLIF, or target function and must preserve single evaluation, NULL-denominator behavior, and the optional alternate result.

Neither language treats SELECT, FROM, JOIN, GROUP BY, query-level WHERE, set operations, DDL, or DML as expression constructs. Semantic Hub generates those clauses from the model and query request.

3. Aggregation mapping

The Semantic Hub value column contains the structural value stored in AggregateDefinition.aggregation. Required and Recommended refer to the upstream OSI proposal. Extension means that Semantic Hub supports the operation but the reviewed OSI expression specification does not require it.

OSI syntax	Semantic Hub value	OSI status	Decomposability	Mapping notes
`SUM(expr)`	`SUM`	Required	Distributive	Direct mapping.
`AVG(expr)`	`AVERAGE`	Required	Algebraic	`AVG` is the preferred serialized SQL spelling.
`MIN(expr)`	`MIN`	Required	Distributive	Direct mapping.
`MAX(expr)`	`MAX`	Required	Distributive	Direct mapping.
`COUNT(*)`	`COUNT_ROWS`	Required	Distributive	`COUNT_ROWS` has no `expression` property.
`COUNT(expr)`	`COUNT_NON_NULL`	Required	Distributive	Counts non-null input values.
`COUNT(DISTINCT expr)`	`COUNT_DISTINCT`	Required	Holistic	Value-distinct, not entity-key deduplication.
`SUM(DISTINCT expr)`	`SUM_DISTINCT`	Required DISTINCT form	Holistic	Value-distinct. OSI requires `DISTINCT` support for `SUM`.
`AVG(DISTINCT expr)`	`AVERAGE_DISTINCT`	Extension	Holistic	Accepted as a Semantic Hub extension; it is not listed as required by the reviewed OSI proposal.
`MEDIAN(expr)`	`MEDIAN`	Required	Holistic	Equivalent to the median operation; do not rewrite unless the target preserves its semantics.
`STDDEV(expr)` or `STDDEV_SAMP(expr)`	`STDDEV_SAMP`	Required	Algebraic	`STDDEV` normalizes to the sample variant.
`STDDEV_POP(expr)`	`STDDEV_POP`	Required	Algebraic	Population variant.
`VARIANCE(expr)` or `VAR_SAMP(expr)`	`VAR_SAMP`	Required	Algebraic	`VARIANCE` normalizes to the sample variant.
`VAR_POP(expr)`	`VAR_POP`	Required	Algebraic	Population variant.
`PERCENTILE_CONT(p) WITHIN GROUP (ORDER BY expr)`	`PERCENTILE_CONT`	Required	Holistic	`expr` maps to `expression`; `p` maps to `aggregation_parameters.percentile`.
`PERCENTILE_DISC(p) WITHIN GROUP (ORDER BY expr)`	`PERCENTILE_DISC`	Required	Holistic	`expr` maps to `expression`; `p` maps to `aggregation_parameters.percentile`.
`APPROX_COUNT_DISTINCT(expr)`	`APPROX_COUNT_DISTINCT`	Recommended	Sketch-based	The target algorithm and error characteristics may vary.
`APPROX_PERCENTILE(expr, p)`	`APPROX_PERCENTILE`	Recommended	Sketch-based	`p` maps to `aggregation_parameters.percentile`; `approximate_accuracy` is a target-neutral hint.
—	`MODE`	Extension	Holistic	Requires a target mapping or an unsupported-feature diagnostic.
—	`ANY_VALUE`	Extension	Distributive	Mergeable, but nondeterministic unless the surrounding contract establishes a deterministic choice.
—	`LIST_AGG`	Extension	Holistic	`delimiter` and `order_by` are structural parameters; ordering is semantically significant.
—	`CORRELATION`	Extension	Algebraic	The second input is `aggregation_parameters.second_field_ref` or `.expression`.
—	`COVAR_SAMP`	Extension	Algebraic	Sample covariance; requires a second input.
—	`COVAR_POP`	Extension	Algebraic	Population covariance; requires a second input.
—	`REGR_SLOPE`	Extension	Algebraic	Requires a second input; preserve argument order during target mapping.
—	`REGR_INTERCEPT`	Extension	Algebraic	Requires a second input; preserve argument order during target mapping.

Decomposability is compiler and materialization guidance, not a model property:

Distributive aggregates can merge partial results of the same operation.
Algebraic aggregates can merge a fixed-size sufficient state, such as sum and count for an average.
Holistic aggregates generally require complete values or an exact-grain result.
Sketch-based aggregates can merge only compatible sketch states; scalar approximate results are not generally mergeable.

Grain, intrinsic filters, ordering, target behavior, and null semantics must also match before a cache or partial aggregate can be reused.

4. Canonical normalization

The parser normalizes accepted function spellings into one Semantic Hub identity:

Parsed GENERIC or OSI form	Canonical Semantic Hub identity
`AVG(expr)`	`AVERAGE`
`COUNT(expr)`	`COUNT_NON_NULL`
`COUNT(*)`	`COUNT_ROWS`
`COUNT(DISTINCT expr)`	`COUNT_DISTINCT`
`SUM(DISTINCT expr)`	`SUM_DISTINCT`
`AVG(DISTINCT expr)`	`AVERAGE_DISTINCT` extension
`STDDEV(expr)` or `STDDEV_SAMP(expr)`	`STDDEV_SAMP`
`VARIANCE(expr)` or `VAR_SAMP(expr)`	`VAR_SAMP`

The authored spelling may be retained with source spans for diagnostics and round-tripping, but aliases must not create different dependency, lineage, cache, or materialization identities.

SUM_DISTINCT and AVERAGE_DISTINCT remove duplicate input values. They do not deduplicate entities. Entity-key deduplication is represented by aggregation_parameters.deduplicate_by_dimensions on SUM or AVERAGE, followed by the aggregate operation. That is a Semantic Hub structural modeling feature with no single OSI aggregate-call equivalent.

5. Conditional aggregation and `AggregateMetric.filter`

OSI requires filtered aggregation through CASE. Semantic Hub exposes the intrinsic predicate separately as AggregateMetric.filter so the predicate remains attached to one metric and cannot accidentally filter sibling metrics.

For example:

name: completed_revenue
metric_type: AGGREGATE
expression: revenue
aggregation: SUM
filter: status = 'COMPLETED'

is compiled conceptually as:

SUM(CASE WHEN status = 'COMPLETED' THEN revenue ELSE NULL END)

The compiler uses function-specific conditional inputs rather than mechanically wrapping every aggregate in the same template:

Semantic Hub definition	Conceptual SQL form
`COUNT_ROWS` with `filter: p`	`COUNT(CASE WHEN p THEN 1 END)`
`COUNT_NON_NULL(expr)` with `filter: p`	`COUNT(CASE WHEN p THEN expr END)`
`COUNT_DISTINCT(expr)` with `filter: p`	`COUNT(DISTINCT CASE WHEN p THEN expr END)`
`SUM(expr)` with `filter: p`	`SUM(CASE WHEN p THEN expr ELSE NULL END)`
`PERCENTILE_CONT` with `filter: p`	Apply the `CASE` to the ordered input while retaining the percentile parameter.
A two-input statistic with `filter: p`	Apply the same predicate to both inputs before null-pair exclusion.

Using NULL for excluded rows preserves aggregate null and empty-set behavior. It is an intermediate input marker and is not replaced by the metric's final null_handling.null_result. A compiler may use an equivalent target construct, such as a native aggregate filter clause, only when it proves semantic equivalence. It must not promote the predicate to the query's shared WHERE clause unless every affected metric branch has the same effective predicate.

6. Import and export rules

When importing OSI expressions, Semantic Hub should:

Parse the declared OSI dialect and preserve the original text and dialect when history is required.
Bind identifiers using the Semantic Hub row or aggregation context and explicit dataset-path rules.
Normalize aggregate aliases and split aggregate syntax into expression, aggregation, and aggregation_parameters where possible.
Represent a metric-local conditional aggregate as AggregateMetric.filter when the CASE is semantically equivalent to excluding rows from that metric's input; otherwise retain the authored CASE in the canonical expression.
Report unsupported or ambiguous constructs instead of silently changing null, distinctness, grain, ordering, or approximation semantics.

When exporting to OSI, Semantic Hub should emit the mapped standard spelling, reconstruct ordered-set syntax where required, and lower AggregateMetric.filter to a semantically equivalent conditional aggregate. Semantic Hub extensions require an agreed extension representation or an explicit unsupported-feature diagnostic.