Overview

lineage@1 is a JSON protocol for answering one question: where did this value come from? It records the data behind a result, what happened to that data, and who or what did the work.

Use it for document extraction, ETL, calculations, model inference, human review, or any system where a result needs an inspectable history.

Protocol at a glance

Every fact in a lineage graph fits one sentence:

The model extractor@2 (agent) performed Extract total (activity), using invoice.pdf (input entity) to produce Total = 42.50 (an output entity). That complete production record is one derivation.

A lineage document therefore has four core primitives:

• entities are immutable pieces of data, such as inputs, evidence, and results
• activities are operations that use or produce entities
• agents are the people, organizations, software, services, or models responsible
• derivations connect one output entity to its producing activity and exact inputs

The same example as JSON

The four primitives stay separate in JSON so each fact is defined once and can be inspected independently.

{
  "format": "lineage@1",
  "entities": {
    "invoice": { "kind": "artifact", "name": "invoice.pdf" },
    "total": { "kind": "value", "path": "/total", "value": 42.5 }
  },
  "activities": {
    "extract-total": {
      "type": "extract",
      "name": "Extract total",
      "status": "ended",
      "associations": [{ "agent": "extractor", "role": "executor" }]
    }
  },
  "agents": {
    "extractor": { "type": "software", "name": "extractor@2" }
  },
  "derivations": [
    {
      "output": "total",
      "activity": "extract-total",
      "inputs": [{ "entity": "invoice", "role": "document", "effect": "direct" }]
    }
  ],
  "outputs": ["total"]
}

Install

npm install @openparser/lineage

The package provides Zod schemas, TypeScript types, graph validation, traversal helpers, a builder, and PROV-JSON export. It also ships the Draft 2020-12 JSON Schema at @openparser/lineage/schema.json. The same lineage@1 schema is available at its canonical URL.

Import

Import validation, construction, and traversal helpers from the package root:

import {
  LineageBuilder,
  LineageDocumentSchema,
  parseLineageDocument,
  type LineageDocument,
} from '@openparser/lineage';

Use parseLineageDocument(json) when reading untrusted JSON. It validates both the wire shape and graph invariants such as resolved references, unique producers, and acyclic derivations.

What to read next