SDK Guide

Building a Document

How to assemble a UPGDocument by hand — the canonical shape, the constraints, and the minimum viable example.

The shape of a UPGDocument

A UPGDocument is a plain JSON object. The format carries a version (UPG_VERSION), a product_id, a flat nodes array, and a flat edges array. Nodes and edges share the same document scope; hierarchy and containment are expressed as edges, not as nested objects.

Every node carries an id, type, title, status, created_at, and an optional properties object. Edges carry an id, type, source_id, and target_id. The version field at the document root pins the spec generation — migrations replay against it when the document is read by an SDK at a later version.

import type { UPGDocument } from '@unified-product-graph/core'
import { UPG_VERSION } from '@unified-product-graph/core'

const doc: UPGDocument = {
  version: UPG_VERSION,
  product_id: 'my-product',
  nodes: [
    {
      id: 'persona-1',
      type: 'persona',
      title: 'The Pragmatic PM',
      status: 'active',
      created_at: '2026-05-13',
      properties: {
        archetype: 'optimizer',
        tools_used: ['Jira', 'Confluence'],
      },
    },
    {
      id: 'job-1',
      type: 'job',
      title: 'Ship features without breaking production',
      status: 'active',
      created_at: '2026-05-13',
    },
  ],
  edges: [
    {
      id: 'edge-1',
      type: 'persona_pursues_job',
      source_id: 'persona-1',
      target_id: 'job-1',
    },
  ],
}