OpenLineage is an open framework for collecting data lineage, built around an extensible specification that lets different systems exchange lineage metadata. It models three core things, datasets, jobs and runs, and lets you attach extra detail through facets.
The three entities
According to the project documentation:
- A dataset is the data being read or written, such as a table or a file path.
- A job is a process that operates on datasets, such as a transformation task.
- A run is one execution of a job.
Think of it as nouns and events. Datasets and jobs are the stable nouns. A run is something that happened at a time, with a start, an end and a result. A lineage event says that this run of this job read these datasets and wrote those.
Facets
The documentation defines a facet as an atomic piece of metadata attached to one of the core entities, and says you can define custom facets. This is where practical value lives. A facet might describe a dataset schema, the code version for a job, or, if you define it, a sensitivity tag or an approval record.
Because facets are separate from the core, teams can start with the basics and add detail as questions arise.
Naming matters more than it sounds
The documentation notes that consistent naming strategies give each entity a unique identifier. If one tool calls a table by a short name and another by its full path, the graph splits in two and lineage looks broken. Agree a naming rule early, write it down, and test it across tools.
Where events go
A configurable backend determines where lineage events are sent. You can send them to a service that stores and displays them, then query it. Choose a backend with access controls, because lineage reveals which sensitive datasets exist and how they flow. Treat that metadata as sensitive too.
Security angles worth thinking about
- Lineage access. Limit who can browse it, as dataset names alone can be revealing.
- Event integrity. If events can be forged, the graph can mislead during an incident. Authenticate senders.
- Coverage. Lineage you cannot trust to be complete gives false comfort, so measure what share of jobs emit events.
- Retention. Keep lineage long enough to answer deletion and audit questions.
A first week plan
Pick one critical pipeline. List its inputs and outputs by hand. Emit events for its runs. Compare the graph with your hand drawn list, and fix mismatches. Only then expand.
For what to record about ML training in particular, see what to record for ML data lineage.
Where Safeguard fits
Safeguard does not replace a lineage tool. It helps with dependency and SBOM scanning for the code that emits and consumes this metadata, and with compliance evidence automation. Free scan: https://gold.safeguard.sh/scan.
Quick check
What is a run in OpenLineage?
A run records a single execution of a job.
What is a facet?
An atomic piece of metadata attached to a dataset, job or run, and you can define custom ones.
Sources
Last reviewed: 19 October 2026.
