SuperAPI AI Directory

speckle-core-object-model

Coding & development

View repository

Updated 10-16 09:56

About this skill

speckle-core-object-model

Quick Reference

Object Model Layers

Layer Type Purpose Key Properties
1. Primitives Base Atomic values and geometry id, applicationId, speckle_type
2. Data Objects DataObject Semantic BIM elements name, properties, displayValue
3. Collections Collection Hierarchical grouping name, collectionType, elements
4. Root Collection Commit root container Top-level collection sent to server
5. Proxies *Proxy Cross-cutting relationships objects (applicationIds), value

Property Prefix Rules

Prefix Effect Example
(none) Inline serialization height = 3.0
@ Detached serialization @displayMesh = mesh
__ Excluded from serialization and hashing __tempCache = data

Core Identity Fields

Field Type Computed? Purpose
id string YES (SHA256 content hash) Global uniqueness via content addressing
applicationId string NO (user-assigned) Round-trip tracking within one source app
speckle_type string YES (from class hierarchy) Type discriminator for deserialization
totalChildrenCount int YES (during serialization) Progress reporting for transports

Critical Warnings

NEVER call get_id() / GetId() inside a loop -- it triggers full recursive serialization. Compute once and store the result.

NEVER modify an object after reading its id -- the hash is invalidated by ANY property change. ALWAYS finalize all properties before computing the id.

NEVER use . or / in dynamic property names -- both SDKs reject these characters. Use camelCase names without path separators.

NEVER store large geometry inline (non-detached) -- ALWAYS use detached properties for meshes and large lists. Inline storage prevents deduplication and lazy loading.

NEVER create cycles in Collection hierarchies -- collections MUST form a strict directed tree. Cycles cause infinite recursion during traversal.

NEVER omit units on geometry objects -- without units, receiving applications cannot scale geometry correctly. A 3-meter wall renders as 3 millimeters.

NEVER assume applicationId is globally unique -- it is unique only within a single source application. Use id for cross-model uniqueness.

NEVER read totalChildrenCount before serialization -- it is only populated during the send operation. Use get_children_count() / GetTotalChildrenCount() for an accurate count.


The Base Class

Every Speckle object inherits from Base. It is the universal ancestor for all data in the Speckle ecosystem.

Python Declaration

from specklepy.objects.base import Base

@dataclass(kw_only=True)
class Base(_RegisteringBase):
    speckle_type = "Base"
    id: Union[str, None] = None
    applicationId: Union[str, None] = None

C# Declaration

[Serializable]
public class Base : DynamicBase, ISpeckleObject
{
    public string id { get; set; }
    public string applicationId { get; set; }
    public string speckle_type => TypeLoader.GetFullTypeString(GetType());
    public int totalChildrenCount { get; set; }
}

Content-Addressed Identity

The id is a deterministic SHA256 hash computed from the serialized JSON of the object. Two objects with identical properties ALWAYS produce the same id. The id is null until serialization occurs -- NEVER assign it manually.


Dynamic vs Typed Properties

Speckle supports a hybrid model: typed properties defined in class declarations, plus dynamic properties added at runtime.

Typed Properties

Defined in class declarations with type hints (Python) or C# property syntax:

@dataclass(kw_only=True)
class Wall(Base):
    speckle_type = "Objects.BuiltElements.Wall"
    height: float = 0.0
    baseOffset: float = 0.0
public class Wall : Base
{
    public double height { get; set; }
    public double baseOffset { get; set; }
    [DetachProperty]
    public List<Base> displayValue { get; set; }
}

Dynamic Properties

Added at runtime via dictionary-style access. ALWAYS serialized and transmitted like typed properties:

obj = Base()
obj["customProperty"] = "hello"
obj["@detachedMesh"] = some_mesh   # @ prefix = detached
var obj = new Base();
obj["customProperty"] = "hello";
obj["@detachedMesh"] = someMesh;   // @ prefix = detached

Property Name Validation

Both SDKs prohibit: empty strings, consecutive @@, names containing . or /.


Detaching

Detaching is Speckle's key optimization for large data. A detached child is serialized separately; the parent stores only a reference (referencedId).

Two Ways to Detach

Dynamic properties -- @ prefix (Python and C#):

beam["@displayMesh"] = get_mesh(element)

The @ is stripped from the final property name during serialization.

Typed properties -- [DetachProperty] attribute (C#):

[DetachProperty]
public List<Base> displayValue { get; set; }

In Python, detachment is controlled by dataclass field metadata on typed properties.

What Detaching Produces

Without detaching (inline):

{ "displayValue": [{ "id": "mesh1", "vertices": [...] }] }

With detaching (reference):

{ "displayValue": [{ "referencedId": "mesh1", "speckle_type": "reference" }] }

Benefits: deduplication, lazy loading, parallel transfer, incremental updates.


Chunking

Chunking splits large flat arrays into smaller segments for efficient transport.

C# [Chunkable] Attribute

[Chunkable(31250)]
[DetachProperty]
public List<double> vertices { get; set; }

Each chunk is stored as a separate detached object. A mesh with 10 million vertices at chunk size 31,250 produces ~320 independently transferable chunks.

Python Equivalent

SpecklePy marks properties as chunkable via dataclass field metadata, achieving the same segmentation.


Decision Tree: Detach vs Chunk vs Inline

Is the property a large flat numeric array (vertices, faces, colors)?
  YES → Use [Chunkable] + [DetachProperty] (C#) or chunkable metadata (Python)
  NO  → Is the property a Base object or list of Base objects?
           YES → Is it >1KB or shared across multiple parents?
                   YES → Detach it (@ prefix or [DetachProperty])
                   NO  → Inline is acceptable
           NO  → Inline (primitive values are ALWAYS inline)

Decomposition: Composed vs Decomposed

State Description When
Composed Nested object tree in memory Working with objects in code
Decomposed Flat set of independent objects by id Storage and transport (send/receive)

Decomposition occurs during serialization (Send). Recomposition occurs during deserialization (Receive). The totalChildrenCount on the root tells transports how many separate objects to expect.


Data Schema Layers

Layer 2: DataObject

@dataclass(kw_only=True)
class DataObject(Base):
    speckle_type = "Objects.Data.DataObject"
    name: str = ""
    properties: Dict[str, object] = field(default_factory=dict)
    displayValue: List[Base] = field(default_factory=list)  # detachable

Application-specific subclasses: QgisObject, BlenderObject.

Layer 3: Collection

public class Collection : Base
{
    public string name { get; set; }
    public string collectionType { get; set; }
    public List<Base> elements { get; set; }  // detachable
}

Collections MUST form a strict directed tree -- no cycles, no shared parents. Other Speckle objects MAY form directed acyclic graphs (DAGs).

Layer 5: Proxy Types

Proxies enable many-to-many relationships in the tree model. Each proxy holds objects (a list of applicationId strings) and a value.

Proxy Type speckle_type Value Type
ColorProxy Speckle.Core.Models.Proxies.ColorProxy int (ARGB)
GroupProxy Speckle.Core.Models.Proxies.GroupProxy (name only)
InstanceProxy Speckle.Core.Models.Instances.InstanceProxy List[float] (4x4 matrix)
InstanceDefinitionProxy Speckle.Core.Models.Instances.InstanceDefinitionProxy List[str] (object ids)
LevelProxy Objects.Other.LevelProxy Base (elevation data)
RenderMaterialProxy Objects.Other.RenderMaterialProxy RenderMaterial

The displayValue Mechanism

displayValue is the universal visual representation for semantic objects. Every DataObject stores its renderable geometry here.

Rules

  • displayValue ALWAYS contains geometry primitives (Mesh, Line, Point)
  • A single object MAY have multiple geometry items in displayValue
  • displayValue is ALWAYS marked as detachable
  • Applications that understand the semantic type MAY reconstruct native geometry; others use displayValue for rendering

Units

Every geometry object MUST include a units field. Supported values:

Value Unit
"m" Meters (server default)
"mm" Millimeters
"cm" Centimeters
"ft" Feet
"in" Inches

Unit conversion is handled by connectors during native format conversion. The server stores geometry in whatever units the sender specified.


Instance/Definition Pattern

For repeated geometry (e.g., 1000 identical chairs):

  1. One InstanceDefinitionProxy stores the geometry once
  2. Multiple InstanceProxy objects reference the same definitionId with different 4x4 transform matrices
  3. Result: 1 definition + 1000 lightweight transform references instead of 1000 full geometry copies

Reference Links

Official Sources