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-08Current · draft

Operationalises RFC 0003 (L2 traversal, governed content sampling, the unified domain-map — everything is an Entity, bridges collapse to edges) and adds the single query surface: OSL-SQL in POST /osl/query (SPEC §8.9) folds retrieval, the Joint record, traversal and the cross-modal join into one semantic dialect, with projection operators. RFC 0002 is superseded by the RETRIEVE relation source.

RFC 0003 · AcceptedRFC 0004 · AcceptedRFC 0005 · Accepted

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 Accepted
0004 Projection operators (encoder + optional decoder) Accepted
0005 OSL-SQL — the single query surface Accepted

“Accepted” is honest: each has an implemented slice in the reference engine but is not marked Implemented until a tagged release cites it in the changelog.

Design principles (binding)

Section titled “Design principles (binding)”

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

  1. MetricFlow pass-through is the compatibility target. Full conformance is not declared until schemas, parser, execution and a cross-version suite prove it; the current subset is documented without over-claiming.
  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”