Robot dataset versioning assigns immutable identities to data states and records how raw episodes become labels, transformed files, splits, statistics and training inputs. Lineage extends that chain through code, environment, model artifacts, evaluation and deployment.
Dates and folder names are not enough. Robot data depends on tool, calibration, firmware, controller, site and operator context, and a corrected label can affect many models. The system must support reproduction, impact analysis and compatible rollback.
Use this guide with the data-quality audit and LeRobotDataset v3 guide. Keep raw captures immutable and create corrections as new derived versions.
Use immutable content identities
Assign hashes or immutable object identifiers to raw files, manifests and derived datasets. A friendly semantic version can describe intent, while the content identity proves which bytes and records were used.
Do not reuse an identifier after editing labels or replacing a camera file. Create a new version that references the parent and the reason for change.
Keep raw captures append-only
Original sensor and command data is evidence. When a timestamp, label or calibration association is wrong, preserve the raw source and create a correction layer or new derived artifact.
Control access and retention according to rights and privacy requirements. Immutability does not mean every person can read sensitive raw data.
| Lineage object | Immutable identity | Required parents | Change creates |
|---|---|---|---|
| Raw episode | Capture checksum | Device and session | New capture |
| Label set | Annotation manifest hash | Episodes and taxonomy | New label version |
| Transform output | Artifact and code hash | Input, code, parameters | New derived version |
| Split | Membership manifest hash | Dataset version | New split version |
| Model | Artifact hash | Data, code, config, environment | New model version |
Build a complete episode manifest
The manifest should name episode, sensors, actions, timestamps, task, outcome, robot, tool, calibration, firmware, software, operator or collection mode, rights and quality status. Store checksums and locations without making storage paths the identity.
Validate referential integrity and required fields automatically. Keep unknown values explicit so downstream filters do not treat missing metadata as a valid default.
Include physical configuration lineage
Robot data semantics change with tool center point, joint zero, gripper fingers, camera extrinsics, payload and control firmware. Link these versions to every session and record mid-session changes as new segments.
A software commit cannot reconstruct a worn cup, moved camera or replaced end effector. Keep maintenance and calibration evidence alongside digital configuration.
Represent transformations as a directed graph
Each transformation records input identities, code revision, dependency environment, parameters, runtime and output identity. Examples include synchronization, filtering, image resize, action normalization, annotation merge and format migration.
A directed acyclic graph makes fan-in and fan-out visible: one model can use several datasets, while one corrected episode can affect many mixtures and releases.
Validate schema migration and semantic preservation
A migration can successfully write new files while changing joint order, units, episode boundaries or missing-value meaning. Run schema checks and replay representative episodes before accepting the derived version.
Use the cross-embodiment action guide when transformations map robot-specific actions. Keep reversible tests and migration reports.
Version train validation and test membership
A split is a first-class artifact containing membership rules and immutable IDs. New data should not silently reshuffle historical test episodes or move derived siblings across partitions.
Link every run to an exact split version. If the evaluation claim changes from new episode to new site or robot, create a new split rather than renaming the old result.
Bind statistics and vocabularies to datasets
Normalization statistics, token vocabularies, task maps and class weights are derived from specific dataset and split versions. Reusing stale statistics after filtering or unit changes can corrupt training while files still load.
Record calculation code and membership. Fit learned preprocessing on training data only and publish its identity with the model.
Link training runs and environments
Capture data and split identities, mixture configuration, code commit, container or dependency lock, hardware, seed, model config, checkpoint selection and metrics. The current MLflow dataset tracking documentation is one tool reference, not a complete robot-specific lineage design.
Run tracking systems only help when inputs are correct and immutable. Verify that logged dataset names resolve to exact manifests rather than mutable aliases.
Publish datasets with durable revision records
The Hugging Face dataset upload documentation explains current Hub publication workflows. A repository commit can provide useful revision identity, while dataset cards, licenses and external artifact hashes still need maintenance.
DVC or object-store manifests can manage large artifacts. No tool automatically captures calibration, rights, label intent or physical configuration unless the workflow supplies them.
Exercise impact analysis and rollback
Select a corrected or withdrawn episode and find every derived dataset, statistic, run, model and deployment that consumed it. Then select a deployed model and reconstruct its sources and evaluation bundle.
Rollback must restore compatible model, preprocessing, schema, action adapter and configuration. Restoring one checkpoint against changed statistics is not a valid rollback.
| Lineage test | Start point | Expected trace | Failure found |
|---|---|---|---|
| Reproduce | Model release | Exact run and artifacts | Mutable alias |
| Source trace | Training batch | Raw episode and transform | Missing parent |
| Impact | Corrected episode | All affected models | Orphan consumer |
| Rights | Withdrawn source | Published derivatives | Untracked copy |
| Rollback | Deployment | Compatible full bundle | Schema mismatch |
Release with a lineage acceptance checklist
Document identifier rules, retention, manifest schema, transformation graph, split governance, run tracking, access control, rights and rollback procedure. Test the graph regularly rather than trusting that links exist.
Close validation with the following checklist.
- Keep raw evidence immutable and corrections versioned.
- Link physical configuration and calibration to sessions.
- Version transforms, splits, statistics and vocabularies.
- Bind every model to exact data and environment artifacts.
- Test reproduction, bidirectional impact analysis and rollback.
Frequently asked questions
Are date-stamped dataset folders sufficient versioning?
No. Dates do not prove content identity, parents, transformation code or split membership.
Should an incorrect raw label be edited in place?
Preserve the original evidence and create a new corrected label or derived dataset version with provenance.
Is the dataset name in a checkpoint enough?
No. Store immutable manifest, split, mixture, statistics, code and environment identities.
Do Hugging Face, DVC or MLflow automatically complete lineage?
No. They provide useful primitives, but robot metadata, calibration, rights and semantic transforms must be captured deliberately.
How should lineage be tested?
Trace a model to raw episodes, a source change to affected deployments and a release through a full compatible rollback.
Immutable-Source and Reproducible-Model Boundary
Lineage is operational evidence, not a naming convention. A release must be reproducible from immutable sources and reversible as a compatible data-model-system bundle.