Skip to main content
Our Data Schemas and object model are still evolving, and there may be discrepancies or incompleteness between our documentation and the latest in development. If you have any questions, please contact us on the Speckle Community Forum: Developers.

​
What is the Data Schema?

The Data Schema is the structuring of properties and geometries at the most granular level. It defines how data from any source application (Revit, Rhino, AutoCAD, etc.) is organized, starting from the smallest building blocks and building up into larger structures.
Important: The “Data Schema” is NOT the same as a “Speckle Model” in the addressing hierarchy. The Data Schema describes the structure of the data itself (how properties, geometries, objects, and collections are organized), while a “Speckle Model” is an organizational container in the addressing system. See the addressing section below for clarification.

​
Projects, Models, and Versions as Addresses

Projects, Models, and Versions form an addressing system that organizes and locates data in Speckle. Behind the scenes, Projects have versions directly—Models are user-facing semantic organization that provide meaning and context. 
User-Facing View:          Behind the Scenes (API):
Project                    Project
  └─ Model (semantic)        └─ Version
      └─ Version                └─ Root Collection
          └─ Root Collection
Projects are top-level containers that organize related work and control access. At the API level, projects have versions directly. See the GraphQL API documentation for the technical implementation. Models are user-facing semantic labels that provide organizational meaning (e.g., “structural”, “MEP”, “design-option-a”). They act as “window dressing” that groups related versions together for easier navigation and understanding, but they don’t change the underlying structure—versions still belong to projects at the API level. Versions are immutable snapshots of data at a specific point in time. Each version references a Root Collection by its object ID, creating a discoverable entry point to the data. Think of this as an addressing system: Project → Schema → Version provides a unique “address” to locate a specific package of information, where Schemas add semantic meaning to help users organize and find their work.

​
Objects and Addressing

Important: Objects can exist in Speckle independently of Projects, Models, and Versions. When an object is sent to a Speckle server, it receives a unique object ID (hash) based on its content. However, without being referenced by a version, the object is effectively unreachable through normal workflows—these are called “orphaned” or “zombie” objects.
  • Orphaned objects exist in the database and have object IDs, but cannot be browsed or discovered through the UI
  • They can still be retrieved if you have the object ID directly
  • To make objects discoverable, they must be referenced by a version (which belongs to a project, and optionally organized under a model)
This separation between object storage and addressing allows for flexible workflows where objects can be created, stored, and later organized into the addressing hierarchy as needed.

​
The Data Schema Structure

The Data Schema organizes data from the most granular level upward:
  1. Properties and Geometries - The atomic building blocks (key-value pairs and geometric primitives), all structured as Base Objects
  2. Objects - Combine properties and geometries into meaningful units (Geometry, DataObject, Instance)
  3. Collections - Organize objects into hierarchies (layers, levels, categories)
  4. Root Collection - The top-level container that holds Collections, Proxies, and Info
  5. Proxies - Encode relationships between objects and shared resources (materials, levels, groups)
  6. Info - Metadata that applies to the entire data package
See the Concepts page for detailed explanations of each component.

​
The Complete Structure

Putting it all together, a complete data package looks like: 
Data Package (at a Version)
│
├── Root Collection
│   ├── Collections (hierarchy)
│   │   └─ Collections
│   │      └─ Objects
│   │         ├── Properties (key-value pairs)
│   │         └── Geometry (in displayValue)
│   │
│   ├── Proxies (relationships)
│   │   └── Reference objects by applicationId
│   │
│   └── Info (metadata)
│       └── Data package-wide data

​
Learning Path

This documentation is organized as a progressive learning experience:
  1. Concepts - Core ideas: Collections, Objects, Proxies, Info
  2. Object Model - How objects are structured and what fields they contain
  3. Geometry Model - How geometry is stored and organized
  4. Proxy Model - How proxies encode relationships
  5. Connector Index - Overview of connector-specific behaviors
Speckle uses a unified Data Schema so that data from any source can be consumed by any receiver. This means you can write code that works with Speckle models without needing to know which application created them. The connector-specific differences are captured in the object properties and hierarchy structure, not in the fundamental Data Schema organization.
The source application’s hierarchy (e.g., Revit’s levels/categories, Rhino’s layers) is preserved in the Collections structure. However, Speckle also imposes its own organizational structure through Proxies, which can create additional relationships that don’t exist in the source application. This allows objects to be organized in multiple ways simultaneously without duplication.