ObjectStackDataset
Dataset protocol schemas
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 { DatasetSchema, DatasetDimensionSchema, DatasetMeasureSchema, DerivedMeasureOp } from '@objectstack/spec/ui';
import type { Dataset, DatasetDimension, DatasetMeasure } from '@objectstack/spec/ui';
// Validate data
const result = DatasetSchema.parse(data);Dataset
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Dataset unique name |
| label | string | Record<string, string> | ✅ | Dataset label |
| description | string | Record<string, string> | optional | Display label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time |
| object | string | ✅ | Base object name |
| include | string[] | optional | Relationship names/paths to join (derived from object graph; max 3 hops) |
| filter | any | optional | Intrinsic dataset scope filter |
| dimensions | { name: string; label?: string | Record<string, string>; field: string; type?: Enum<'string' | 'number' | 'date' | 'boolean' | 'lookup'>; … }[] | ✅ | Groupable axes |
| measures | { name: string; label?: string | Record<string, string>; aggregate?: Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'>; field?: string; … }[] | ✅ | Aggregatable values |
| protection | { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } | 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 | Record<string, string> | optional | Display label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time |
| 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 | Record<string, string> | optional | Display label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time |
| aggregate | Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'> | optional | Aggregation (sum/avg/count/...); omit when derived is set |
| field | string | optional | Aggregated field; optional for count(*) |
| filter | any | optional | |
| format | string | optional | |
| currency | string | optional | Display currency code (ISO 4217) |
| derived | { op: Enum<'ratio' | 'sum' | 'difference' | 'product'>; of: string[] } | optional |
DerivedMeasureOp
Allowed Values
ratiosumdifferenceproduct