Publish, load, and integration depth

Choose publish-only or publish-and-load for host connectors—and how far to invest beyond baseline publish extraction.

The first decision for host connectivity is direction: whether the integration publishes to Speckle, loads from Speckle, or does both. The second is depth: how much interoperability you implement on the load path (if any).

Do not design for round-tripping via Speckle. Speckle is not a bidirectional model exchange format. Publish and load are separate workflows with different goals. Baseline publish depth is sufficient for many integrations; deeper load-side work is a deliberate product choice, not a requirement.

Direction: publish, load, or both

Mode	What it means	Typical use
Publish only	Host → Speckle (create versions). No load UI or conversion back into the host.	Most new CAD/BIM/structural connectors: extraction, coordination, dashboards, automation, analysis results in the cloud.
Publish and load	Both directions in one connector—but not semantic round-trip.	Desktop hosts where users publish their model and load others’ geometry or metadata for coordination (load-side depth beyond publish).
Receive / load only	Speckle → tool only. No publish path from that application.	Uncommon for design hosts. Example: Power BI (speckle-powerbi repo)—consumes published versions only. Not typical for new Revit-, Rhino-, or Tekla-style connectors.

Most new host integrations should assume publish only until there is a clear user need to load Speckle data back into that host.

Receive-only is not a default connector shape. If you are building inside a CAD/BIM/structural application, implement publish depth first. Treat load only as a specialised product model like analytics and reporting tools, not as the third equal option for every host.

SDK and API terms may say send and receive; user-facing connector docs often say publish and load. The concepts align: publish/send creates a version; load/receive materializes objects from a version into the host.

Integration depth (increasing effort)

Depth describes how much you invest after the host can publish reliably. Each step adds load-side capability. Many connectors never go beyond publish.

Depth	Focus
Publish	Geometry, metadata, analysis results into Speckle
Load: reference geometry	Coordination meshes and similar in the host
Load: interop lite	Category mapping, metadata on load
Load: pragmatic interop	Selected native object translations

1. Publish

   Goal: Reliable extraction from the host into Speckle.

   Includes:

   • Geometry (meshes, curves, points, display values)
   • Metadata (parameters, identifiers, discipline-specific properties)
   • Analysis or results payloads where the host exposes them

   Outcome: New versions in Speckle that downstream tools, viewers, and automations can consume without any load path in the host.

   When to stop: Coordination, visualization, ETL, reporting, or cloud processing only need published data. Most connectors can ship at publish depth.

   Speckle connectors (examples):

   • ETABS — publish-only; structural model and analysis-oriented publish
   • Tekla Structures — publish-only
   • Navisworks — publish-only; coordination and federation publish
   • Revit, Rhino, Grasshopper, Blender, Archicad, Civil 3D, AutoCAD, SketchUp — publish (and load where supported)

   Docs: Data & build order · Desktop host · Data schema

2. Load: reference geometry

   Goal: Bring Speckle geometry into the host as reference content—not editable native model semantics.

   Typical behaviour:

   • Place meshes or simplified geometry for coordination
   • Optional transforms, layers, or visibility by source model
   • No expectation that edits in the host write back to Speckle

   Requires: Publish and load in the product sense, but still not round-trip.

   Speckle connectors (examples):

   • Revit — default load as Direct Shapes (generic models) for coordination geometry
   • Rhino, Blender, SketchUp, Archicad, Civil 3D, AutoCAD — load workflows documented per connector

   Docs: Display values · Geometry schema

3. Load: interop lite

   Goal: Smarter load without full native object reconstruction.

   Typical behaviour:

   • Category mapping — map Speckle types or layers to host categories, families, or styles
   • Metadata transfer — attach parameters or properties to reference elements
   • Still pragmatic: partial coverage, documented limitations

   Tradeoff: More useful than raw reference geometry; less cost than native translation.

   Speckle connectors (examples):

   • Revit — materials and parameters on loaded objects; category and type behaviour described in connector FAQ
   • Grasshopper — receive workflows with property and parameter-driven filtering

   Docs: Connector schemas · Revit user guide

4. Load: pragmatic interop

   Goal: Recreate selected native host objects from Speckle data where it is worth the maintenance.

   Typical behaviour:

   • Native walls, members, grids, or discipline-specific types where converters exist
   • Explicit scope: which types translate, which stay as reference geometry
   • Document what is not supported

   Tradeoff: Highest implementation and test burden. Still not round-trip: publish and load remain separate operations with different conversion logic.

   Speckle connectors (examples):

   • Revit — native element load where supported by the connector
   • Blocks as Families — load block instances as Revit families (optional load setting)

   Docs: Blocks as Families · Revit load FAQ

Connector depth varies by host and version. Use each connector’s user guide for supported publish types, load settings, and limitations—the lists above are illustrative, not exhaustive.

How depth maps to publish / load modes

Mode	Integration depth usually in scope
Publish only (typical for new hosts)	Publish
Publish and load (desktop connectors with load)	Publish always; load-side depths only if load is a product requirement
Receive / load only (e.g. Power BI)	Consume published versions in the tool; no publish from that app

Product and engineering implications

• Scope publish first. Prove publish quality (units, stable ids, display values, analysis payloads) before investing in load converters.
• Separate conversion codebases. Publish converters and load converters should not assume symmetry; sharing utilities is fine, sharing 1:1 reversible mappings is not.
• Set user expectations. Document supported publish types, load types, and that edits in the host after load do not sync back via Speckle.
• Prefer downstream consumption in Speckle (viewer, dashboards, Automate, other connectors) instead of load when the goal is coordination only.

Related

Data & build order

Projects, models, versions, and suggested build sequence.

Desktop host

Add-ins and agents that implement publish and load.

Connector schemas

Per-host data shapes for published objects.

Resources

SDKs and reference repositories.