Skip to content
OpenDome

OSL specification

The OSL specification is the normative contract (RFC 2119). It defines every primitive, every field and every error code. The Concepts page teaches the model; the spec binds it. Apache-2.0

Version history

Section titled “Version history”

apiVersion: osl.opendome.eu/v1 covers the whole v1.x line. Minor versions are additive and read-compatible; breaking changes wait for v2.

v1.0Baseline

The foundation: MetricFlow superset (structured plane) + UnstructuredFacet (unstructured plane) + the JointEntity bridge, and the four conformance levels.

RFC 0002 · semantic_match · Accepted

v1.1Design

The relationships & resolution model: structured↔structured via shared entities, N-N via bridges, honest structured↔unstructured joins on authoritative keys, multi-hop, and fast resolution.

RFC 0003 · Relationships & resolution

v1.22026-06Current · draft

Operationalises RFC 0003: L2 traversal, governed content sampling (ACL + server-side redaction) and the unified domain-map (everything is an Entity; bridges collapse to edges). Lance + Governance conformance levels expand.

RFC 0003 · Implemented

v1.32026-07Next

The single query surface (OSL-SQL): /osl/query becomes the sole consumption endpoint, folding retrieval, joins and traversal into one semantic SQL dialect — plus projection operators. RFC 0002 is superseded by the RETRIEVE relation source.

RFC 0005 · OSL-SQL · DraftRFC 0004 · Projection operators · Draft

v2Future

Reserved for breaking changes and work explicitly outside the v1.x boundary (e.g. content↔content inference / reasoning).

The nine primitives

Section titled “The nine primitives”

SemanticModel, Metric, SavedQuery, TimeSpine, UnstructuredFacet, JointEntity, Lexicon, DataContract, PolicyBinding. Each carries apiVersion: osl.opendome.eu/v1 and a kind. JSON Schemas are published one per primitive plus a master manifest schema.

RFCs

Section titled “RFCs”

Substantive changes go through the RFC process.

# Title Status
0002 semantic_match / MATCHES predicate Superseded
0003 Relationships, resolution & queryability Implemented
0004 Projection operators (encoder + optional decoder) Draft
0005 OSL-SQL — the single query surface Draft

Design principles (binding)

Section titled “Design principles (binding)”

If a proposal breaks one of these, it’s rejected:

  1. MetricFlow pass-through is sacred. Any valid dbt-sl project is valid OSL.
  2. Lance is first-class, not an addon — its own primitives, schema, errors, lineage.
  3. The customer declares, the engine executes. The spec says what exists, never how it runs.
  4. Every decision is auditable — query, retrieval, PDP decision all emit OpenLineage.
  5. Versioning is a contract. …/v1 won’t break your YAML for the whole v1 line; breaking changes wait for v2.

Versioning guarantee

Section titled “Versioning guarantee”

apiVersion: osl.opendome.eu/v1 is a promise not to break your YAML across the entire v1 line. Endpoints may add optional fields within v1.x; clients must ignore unrecognized fields. Anything deprecated in v1.x stays functional for at least two consecutive minor versions; removal requires v2, served alongside v1 for that window.

Section titled “Related”