---
title: Dataset
description: Dataset protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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).

<Callout type="info">
**Source:** `packages/spec/src/ui/dataset.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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);
```

---

## Dataset

### 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 to join (derived from object graph) |
| **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.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'>` | ✅ | Aggregation (sum/avg/count/...) |
| **field** | `string` | optional | Aggregated field; optional for count(*) |
| **filter** | `[__schema0](./__schema0)` | optional |  |
| **format** | `string` | optional |  |
| **certified** | `boolean` | ✅ | Blessed metric (governance checkpoint) |
| **derived** | `Object` | optional |  |


---

## DerivedMeasureOp

### Allowed Values

* `ratio`
* `sum`
* `difference`
* `product`


---

