We asked customers to share recordings, got sixty, and read the entity trees. The variation was much larger than we expected, and it correlated with something useful.
Three patterns
By physical containment. world/robot/arm/gripper/camera. The tree mirrors
what is bolted to what.
By producing system. perception/detector/output,
planning/costmap. The tree mirrors the software architecture.
Flat. cam0, cam1, lidar, pose. No
hierarchy at all.
The correlation
Teams using physical containment answered "why did this fail" noticeably faster. Not because of taste — because of what the hierarchy does.
Transforms compose down the tree. If your hierarchy is physical, then logging one transform per joint is enough, and everything beneath a joint moves correctly for free. If your hierarchy is architectural, the camera is not beneath the arm that carries it, so you end up computing world poses by hand and logging them per entity. That is more code, and it is code that can disagree with reality.
The flat teams had the worst time. Every spatial relationship lived in someone's head.
The awkward part
Provenance is a real question too — "which node produced this?" is worth being able to answer. The physical-containment teams handled it by keeping it as metadata rather than structure.
Structure should encode the relationship you need to compute with. Everything else is a column.
What we changed
Our own examples were inconsistent — some physical, some architectural, chosen by whoever wrote them. Documentation that models the thing you are recommending is worth more than documentation that recommends it, so we rewrote them all to be physical, and said why.