ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

DataViewSpec Overview

DataViewSpec is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (source.primary, source.item) and describes how the UI should present, sort, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.

field.key.label
DataViewSpec Overview
field.version.label
field.type.label
field.title.label
DataViewSpec Overview
field.description.label

DataViewSpec is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (source.primary, source.item) and describes how the UI should present, sort, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.

field.tags.label
tech,contracts,data-views
field.owners.label
field.stability.label
public

Purpose

`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.

Schema Highlights

•

**DataViewMeta**: ownership metadata plus an entity slug.

•

**DataViewSource**: primary/item operation refs, mutation operation refs, refresh events, and optional database binding.

•

**DataViewConfig**: list/detail/table/grid definitions with fields, filters, actions, collection preferences, and optional `view.management` metadata.

•

**DataViewAction**: declarative actions with optional placement, intent, selection scope, approval/destructive boundary, and operation refs.

•

**DataViewConfig.management**: optional command-center metadata for header copy, master-detail layout, toolbar groups, selection/bulk actions, detail empty states, personalization keys, and RoleMorph refs.

•

**DataViewSections**: detail-view sections discriminated by `kind` (default `'fields'`). A `'relationship'` section carries a `relationship: DataViewSectionRelationship` (`key`, `cardinality`, `dataPath?`/`source?`/`specKey?`/inline `fields?`, `displayMode?`, `limit?`, `emptyState?`) and renders a related-record collection. The declared relation `OpRef` is host-executed; the design-system performs no I/O.

Authoring Guidelines

1.

Keep fetching logic inside contract operations; DataViewSpec only references them via `source`.

2.

Use `view.management` for entity-management projection metadata only.

3.

Keep persistence, validation, modal flow, destructive confirmations, and network side effects host-owned or FormSpec-owned.

4.

Prefer additive metadata and version specs deliberately when field membership, ordering, or semantics change.

5.

Declare relationships via a `kind: 'relationship'` section; supply related records embedded (`dataPath`) or host-supplied — the design-system never executes the relation `OpRef`.