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

EdgeSpec — Graph Edge Contract Type

EdgeSpec is the Layer-1 declarative type for a relationship between two entity slugs in a ContractSpec graph view. Required fields: id, from, to, relation, cardinality.

field.key.label
EdgeSpec — Graph Edge Contract Type
field.version.label
field.type.label
field.title.label
EdgeSpec — Graph Edge Contract Type
field.description.label

EdgeSpec is the Layer-1 declarative type for a relationship between two entity slugs in a ContractSpec graph view. Required fields: id, from, to, relation, cardinality.

field.tags.label
tech,contracts,entities,edge,graph
field.owners.label
field.stability.label
public

Purpose

`EdgeSpec` describes a graph edge (relationship) between two entity types in a ContractSpec graph view.

Fields

| Field | Type | Required | Description | |---------------|---------------------------------------------------------------|----------|--------------------------------------------| | `id` | `string` | ✅ | Stable edge identifier | | `from` | `string` | ✅ | Entity key of the source node | | `to` | `string` | ✅ | Entity key of the target node | | `relation` | `string` | ✅ | Semantic relation name | | `cardinality` | `'one-to-one' \| 'one-to-many' \| 'many-to-one' \| 'many-to-many'` | ✅ | Cardinality | | `directed` | `boolean` | — | Defaults to `true` (from → to) | | `inverse` | `string` | — | `id` of the inverse edge spec | | `traversal` | `{ strategy?, maxDepth? }` | — | Graph traversal hints | | `label` | `string` | — | Human-readable edge label in graph views | | `attributes` | `Record<string, unknown>` | — | Domain-specific rendering/rule metadata |

Layer Roadmap

•

**Layer 1** (current): id + from/to + relation + cardinality. No DB modeling.

•

**Layer 2** (Phase 2): full `EntitySpec<TFields>` + edges via `defineContractEntity`.

Example

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

const UserToProjectEdge = defineContractEdge({
  meta: { key: 'user-to-project', version: '1.0.0', description: '...', stability: 'stable', owners: [], tags: [] },
  edge: {
    id: 'user-to-project',
    from: 'user',
    to: 'project',
    relation: 'has-many',
    cardinality: 'one-to-many',
    directed: true,
  },
});