Skip to main content
This page provides detailed explanations of the fundamental concepts that make up every Speckle data package, building from the most granular level upward. For a high-level overview, see the Overview page.

​
Data Model vs Speckle Model

Important: The “Data Model” and “Speckle Model” are not synonymous. They refer to completely different concepts:
  1. Data Model: The structuring of properties and geometries at the most granular level, building up into Objects, Collections, and data packages. This is what this documentation describes.
  2. Speckle Model: A user-facing organizational container in the addressing hierarchy (Project → Model → Version) that provides semantic meaning. Models are “window dressing” that help organize versions—behind the scenes, versions belong directly to projects.
When we refer to “the data model” or “a data package” in this documentation, we’re talking about how properties, geometries, objects, collections, proxies, and info are structured together—the actual data that exists at a specific version address.
These terms refer to different concepts:
  • Data Model: The structuring of properties, geometries, objects, collections, proxies, and info
  • Speckle Model: An organizational label in the addressing system (Project → Model → Version)
To avoid confusion:
  • Use “Data Model” when referring to the structure of the data itself
  • Use “Speckle Model” or just “Model” when referring to the addressing/organizational container
  • Use “data package” or “Root Collection” when referring to the actual data at a version
See the Overview for more on how Projects, Models, and Versions work as addresses.

​
Properties and Geometries

At the most granular level, the Data Model structures:
  • Properties: Key-value pairs that store metadata and attributes (e.g., name: "Wall 1", material: "Concrete", height: 3000)
  • Geometries: Geometric primitives that define shape and form (e.g., Point, Line, Curve, Mesh, Brep)
All properties and geometries are structured as Base Objects. The Base class is the foundation of the Data Model—every Speckle object inherits from Base. A Base object is essentially a collection of properties that can be either:
  • Tightly typed (static): Properties defined in the class with type hints (e.g., Point.x: float, Mesh.vertices: List[float])
  • Loosely typed (dynamic): Properties added at runtime without predefined types (e.g., wall.customParameter = "value")
Base provides:
  • Identity: Each object has a unique hash (object ID) based on its content
  • Property collection: Combines tightly typed and loosely typed properties in a single object
  • Serialization: Automatic conversion to/from JSON for storage and transport
  • Type information: The speckle_type field identifies the object’s type
These are the atomic building blocks that combine to form objects.

​
Objects

Objects are the actual data elements in a data package. They’re atomic, selectable elements that typically have a visual representation. There are three types of objects:
  1. Geometry - A single piece of geometry (curve, mesh, brep, etc.) with minimal properties
  2. DataObject - A group of geometry representing a BIM element with rich properties (e.g., a wall, column, door)
  3. Instance - A transform and pointer to a Definition proxy, representing a block reference or instance
Every object has:
  • An identity (id, applicationId)
  • A type (speckle_type)
  • Properties (metadata and data - key-value pairs)
  • Geometry (stored in displayValue - geometric primitives)
Geometry objects are primarily geometric primitives (Point, Line, Mesh, etc.) with minimal properties. DataObject objects are BIM elements that combine multiple geometries with rich properties (like a wall with material, dimensions, and type information). DataObjects typically contain multiple geometry objects in their displayValue array, along with extensive property data.

​
Collections

Collections are organizational containers that create a hierarchy. They don’t contain data themselves—they organize objects. Collections have an elements property that contains their child objects and nested collections. Collections can be nested to create hierarchies: 
Collection (e.g., "Level 1")
├── Collection (e.g., "Walls")
│   └── Object (a wall)
│       ├── Properties (name, material, height, etc.)
│       └── Geometry (in displayValue)
└── Collection (e.g., "Doors")
    └── Object (a door)
        ├── Properties (name, type, etc.)
        └── Geometry (in displayValue)
Nested collections typically represent organizational structures from the source application:
  • Revit: File → Level → Category → Type
  • Rhino: File → Layer → Sublayer
  • AutoCAD: File → Layer
Collections can be nested to any depth, but most connectors use 2-4 levels.

​
Root Collection

The Root Collection is always the top-level container for a data package at a version. It contains the collections hierarchy, proxies, and info.
Yes! Collections can be nested to any depth. However, most connectors use a predictable pattern (2-4 levels) based on the source application’s organizational structure. The nesting depth is determined by the connector, not by Speckle’s data model.

​
Proxies

Proxies encode relationships between objects and shared resources. They allow objects to participate in multiple organizational systems without duplicating the objects themselves. For example, a single wall object can be:
  • On “Level 1” (via a Level proxy)
  • In “Exterior Walls” group (via a Group proxy)
  • Using “Concrete” material (via a RenderMaterial proxy)
All without creating multiple copies of the wall. Proxies are stored at the Root Collection level and reference objects by their applicationId.
Proxies solve the problem of overlapping hierarchies. A wall might belong to a level (spatial), a group (functional), and use a material (visual). If we only used collections, we’d have to choose one hierarchy or duplicate the wall. Proxies let us have all three relationships simultaneously without duplication.

​
Info

Info contains metadata that applies to the entire data package. This might include:
  • Views - Camera objects from 3D views
  • Reference Point Transform - Transform matrix for coordinate system adjustments
  • Analysis Results - Data package-wide analysis data
Info fields are optional and connector-specific. Not all data packages have Info fields.

​
How They Work Together

Data Package (at a Version)
│
├── Root Collection
│   ├── Collections (hierarchy)
│   │   └── Objects (data)
│   │
│   ├── Proxies (relationships)
│   │   └── Reference objects by applicationId
│   │
│   └── Info (metadata)
│       └── Model-wide data
The hierarchy (Collections) organizes objects spatially or categorically. Proxies add additional relationships (materials, groups, levels) that cross-cut the hierarchy. Info provides context about the entire data package.
Yes, for simple use cases you can traverse just the Collections to find Objects. However, you’ll miss important relationships like material assignments, group memberships, and level associations that are encoded in proxies. Most real-world workflows need both. See the SDK documentation for traversal patterns and examples.

​
Next Steps

Now that you understand the concepts, let’s dive into the technical details: