Speckle Core Object Model

speckle-core-object-model

Quick Reference

Object Model Layers

Property Prefix Rules

Core Identity Fields

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

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.

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:

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

• references/methods.md -- API signatures for Base, DataObject, Collection, and Proxy types
• references/examples.md -- Working code examples for creating and inspecting objects
• references/anti-patterns.md -- What NOT to do with Base objects

Official Sources

• https://docs.speckle.systems/developers/data-schema/overview
• https://docs.speckle.systems/developers/data-schema/geometry-schema
• https://speckle.guide/dev/base.html
• https://speckle.guide/dev/objects.html