Dataset

Analytics Dataset — the one semantic layer (ADR-0021).

A dataset is a named, reusable analytical definition: a base object, the

relationships to include (joins are derived from the object graph — the

author never writes an ON clause), and the declared dimensions

(groupable axes) and measures (aggregatable values). It is deliberately

SMALLER than QuerySchema: no raw SQL, no hand-authored join predicates,

no window/having grammar in the author surface.

Presentations (report / dashboard) bind to a dataset by reference and

pick dimensions/measures by name. The dataset compiles to the existing

Cube analytics runtime (ADR-0021 D-A=(c)); RLS / tenant scoping is enforced

by the runtime per joined object (D-C), never declared here.

Naming: this module owns the high-prior dataset / dimension / measure

vocabulary (LookML / dbt / Cube / PowerBI). The Zod export identifiers are

Dataset-prefixed (DatasetDimensionSchema, DatasetMeasureSchema) so they

do not clash with the Cube layer's DimensionSchema / MetricSchema in

data/analytics.zod.ts while the two layers coexist (Phase 1). The Cube

layer is absorbed/retired in a later phase (D-A).

Source: packages/spec/src/ui/dataset.zod.ts

TypeScript Usage

import { Dataset, DatasetDimension, DatasetMeasure, DerivedMeasureOp } from '@objectstack/spec/ui';
import type { Dataset, DatasetDimension, DatasetMeasure, DerivedMeasureOp } from '@objectstack/spec/ui';

// Validate data
const result = Dataset.parse(data);

Properties

Property	Type	Required	Description
name	`string`	✅	Dataset unique name
label	`string`	✅	Dataset label
description	`string`	optional	Display label (plain string; i18n keys are auto-generated by the framework)
object	`string`	✅	Base object name
include	`string[]`	optional	Relationship names/paths to join (derived from object graph; max 3 hops)
filter	`[__schema0](./__schema0)`	optional	Intrinsic dataset scope filter
dimensions	`Object[]`	✅	Groupable axes
measures	`Object[]`	✅	Aggregatable values
protection	`Object`	optional	Package author protection block — lock policy for this dataset.
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

DatasetDimension

Properties

Property	Type	Required	Description
name	`string`	✅	Dimension name — referenced by presentations
label	`string`	optional	Display label (plain string; i18n keys are auto-generated by the framework)
field	`string`	✅	Base field, or `relationship[.relationship].field` path
type	`Enum<'string' \| 'number' \| 'date' \| 'boolean' \| 'lookup'>`	optional
dateGranularity	`Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>`	optional

DatasetMeasure

Properties

Property	Type	Required	Description
name	`string`	✅	Measure name — e.g. "revenue"; defined once
label	`string`	optional	Display label (plain string; i18n keys are auto-generated by the framework)
aggregate	`Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>`	optional	Aggregation (sum/avg/count/...); omit when `derived` is set
field	`string`	optional	Aggregated field; optional for count(*)
filter	`[__schema0](./__schema0)`	optional
format	`string`	optional
currency	`string`	optional	Display currency code (ISO 4217)
certified	`boolean`	✅	Blessed metric (governance checkpoint)
derived	`Object`	optional

DerivedMeasureOp

Allowed Values

ratio
sum
difference
product

Dataset

On this page