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

DataViewGraphSpec & DataViewGraphSource

DataViewGraphSpec is the sibling-type contract for graph and timeline-graph data views. DataViewGraphSource is the discriminated union of three data-fetching strategies: inline-op, two-op, and entity-declarative (requires EntityRegistry at render time).

field.key.label
DataViewGraphSpec & DataViewGraphSource
field.version.label
field.type.label
field.title.label
DataViewGraphSpec & DataViewGraphSource
field.description.label

DataViewGraphSpec is the sibling-type contract for graph and timeline-graph data views. DataViewGraphSource is the discriminated union of three data-fetching strategies: inline-op, two-op, and entity-declarative (requires EntityRegistry at render time).

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

Purpose

`DataViewGraphSpec` extends the data-view contract system for graph and timeline-graph experiences. It is a **sibling type** to `DataViewSpec`: both are accepted by `defineDataView()`, discriminated at runtime by `view.kind`.

•

`view.kind ∈ {graph, timeline-graph}` → `DataViewGraphSpec` branch

•

`view.kind ∈ {list, detail, table, grid, timeline}` → `DataViewSpec` branch

`DataViewSource` shape is **intentionally unchanged** — no `primary?` optionalisation, no `graph?` field added.

DataViewGraphSource variants

`inline-op`

Single operation returns both nodes and edges in one payload. Paths are dot-notation selectors into the result object.

No EntityRegistry precondition.

source: {
  variant: 'inline-op',
  primary: { key: 'graph.getContractGraph', version: '1.0.0' },
  nodesPath: 'data.nodes',
  edgesPath: 'data.edges',
}

`two-op`

Separate operations for nodes and edges. Use when your API splits the graph across two endpoints.

No EntityRegistry precondition.

source: {
  variant: 'two-op',
  nodes: { key: 'graph.getNodes', version: '1.0.0' },
  edges: { key: 'graph.getEdges', version: '1.0.0' },
}

`entity-declarative`

Derives graph structure from a registered entity slug and optional edge declarations. The renderer resolves the entity from the `EntityRegistry` at render time.

**⚠ Precondition (C12)**: `EntityRegistry` MUST be loaded before this view renders. The renderer asserts `EntityRegistry.isLoaded()` and throws if the registry is absent. `inline-op` and `two-op` do NOT share this precondition.

source: {
  variant: 'entity-declarative',
  entity: 'user',
  edges: [{ from: 'user', to: 'project', relation: 'has-many' }],
}

Example

import { defineDataView } from '@lssm-tech/lib.contracts-spec';

export const ContractGraphView = defineDataView({
  meta: { key: 'contractspec.graph', version: '1.0.0', entity: 'contract', ... },
  source: {
    variant: 'inline-op',
    primary: { key: 'graph.getContractGraph', version: '1.0.0' },
    nodesPath: 'nodes',
    edgesPath: 'edges',
  },
  view: { kind: 'graph', layout: { kind: 'dag', direction: 'TB' }, nodeKindField: 'type' },
});