Graph model

Read a lineage graph as a set of sentences: an activity, run by an agent, used some entities to produce another entity. Each such production record is a derivation. New operations append new sentences without erasing the old ones.

EntityActivityAgentCurrent output

One derivation

invoice.pdf

entity · artifact

extract-total

activity · extract

associated with

extractor@2

agent · software

total

$42.50 · in outputs[]

The derivation names one output. The activity may appear in other derivations when it produced several entities.

Append-only correction

total

$42.50 · entity kept

confirm-total

activity · review.confirm

associated with

analyst@example.com

agent · person

corrected-total

$47.50 · in outputs[]

The prior entity stays in the graph. Update outputs to point at the corrected value.

Entities

An entity is an immutable datum at one point in its history. Its kind describes its role:

• value for structured or scalar data
• artifact for documents, files, and other durable inputs
• evidence for source material supporting a result
• decision for producer-settled answers and outcomes, including extracted fields, approvals, and rejections
• collection for a named group of entities

Use RFC 6901 JSON Pointers in path to locate values inside larger JSON objects.

Activities

An activity is an operation that uses entities and produces new ones. The open type field supports domain operations such as ocr, extract, compute, normalize, infer, and review.confirm.

Activities can record status, timing, implementation metadata, and associations with responsible agents.

Agents

Agents identify the people, organizations, software, services, or models responsible for an entity or activity. Attributions connect agents to entities; associations connect agents to activities.

Derivations

Each derivation names:

1. one output entity
2. the activity that produced it
3. the input entities that activity used

Inputs can include a semantic role and a direct or indirect effect. The output-centric shape makes immediate sources easy to inspect while supporting multi-input operations. One derivation always has one output; an activity that produces several outputs is named by several derivations.

Append new history

When a value is normalized, recalculated, inferred, or confirmed as a correction, create a new entity and activity. Keep the previous entity in the graph.

Human review follows the same model: the reviewer is an agent, the confirmation is an activity, and a value that differs from extraction is a new entity derived from the machine result. A confirmation that names the current value is a sign-off on that entity rather than a new node.

Existing entities and derivations remain immutable. The document-level outputs array identifies the current result projection and can point to newer entities as the graph grows.

Approvals

An entity can carry approvals, each naming the agent who stands behind that exact value and when they approved it. Standing belongs to the entity and does not propagate to its inputs or outputs. A correction is still represented by a new entity, activity, and derivation; approving an unchanged value adds standing without inventing another value node.

See OpenParser human review for a profile that projects signed confirmations into this core field.

Validation and traversal

LineageDocumentSchema validates both JSON shape and graph coherence. It rejects:

• unresolved references
• duplicate producers
• self-dependencies
• derivation cycles

LineageBuilder provides programmatic construction with the same validation. Traversal helpers return entity ancestors, descendants, and topological order.