We have fairly extensive documentation covering this in more detail:
Speckle represents building data as a directed acyclic graph (DAG), where objects reference other objects and structure is expressed through relationships rather than strict hierarchies. The schemas above describe how each connector maps into that model.
You can reference the individual connector schemas for specifics, but the more useful framing is that Speckle is not converging toward a single canonical model tree. Instead, connectors are aligning around a set of shared principles while still reflecting the realities of their source systems and primary downstream use cases.
Core Principles
At a high level, the object model can be understood in three parts:
-
Collections
Used for grouping, traversal, and contextual structure
-
DataObjects
Domain objects carrying identity, properties, and semantics
-
Geometries
The visual or spatial representation, often reused via instancing or proxies
These are combined differently per connector, but the same conceptual separation applies.
-
Objects over files
Data is decomposed into addressable objects with stable identity. The tree is a transport and grouping mechanism, not the source of truth.
-
Transport efficiency and deduplication
Patterns such as geometry proxies (e.g. definitionGeometry) exist to reduce duplication and payload size.
-
Loose structural contracts
Connectors are not forced into a single tree shape. Structure reflects the source system rather than an imposed standard.
-
Property-centric interoperability
Downstream workflows should rely on properties and object types rather than exact tree position.
-
Progressive normalisation
With respect to what you describe as drift, in Speckle there is convergence toward more predictable patterns, but not strict standardisation.
Connector-Specific Notes
Revit
Revit is currently the most mature example of instancing and geometry reuse via definitionGeometry. It is often the leading implementation of these patterns, but it is not a reference model that other connectors must follow. Its structure reflects Revit’s internal element-definition relationship.
IFC
The IFC uploader now builds on a graph derived from IfcOpenShell and deliberately exposes multiple access patterns within that same graph.
- There is an object-centric view (e.g. interacting directly with IfcSite and other entities)
- There is also a collection/decomposition view within the same graph
This dual approach is intentional. IFC encodes both semantic relationships and hierarchical decomposition. Different users need different traversal modes, so both are preserved rather than collapsed into a single structure.
Navisworks
Navisworks behaviour is shaped heavily by its role as an aggregation layer over multiple source formats.
-
The connector supports two modes:
- Flat list (default)
- Scenegraph-aligned hierarchy (optional)
-
The default was switched to flat because the dominant use case is analytics (e.g. Power BI), where a flattened structure reduces friction for users who are not traversing hierarchies.
-
The connector now also adopts instancing and will use it wherever it can be reliably inferred.
However, because Navisworks aggregates data from multiple upstream tools with different internal representations, it is not always possible to deterministically identify reusable definitions. In those cases, the connector falls back to explicit representations.
Documentation
Summary
Across all connectors, the direction of travel is consistent:
- Reduce duplication
- Improve transport efficiency
- Make data easier to consume
But the tree structure itself is not treated as a strict contract. It will continue to reflect both the source system and the dominant downstream workflows, often exposing multiple valid ways to traverse the same underlying data.
We apply these same principles across every connector we build. Each connector follows the same underlying philosophy, but adapts its structure to the constraints and behaviours of its source system rather than forcing a single unified model.
An exception is Vectorworks, where the connector is developed by Vectorworks themselves against the open Speckle specification. As such, it adheres to the same underlying principles, but its implementation decisions are owned by their team.
