Simple vs federated entities
Every entity is one of two shapes: simple or federated. The runtime
treats them identically - the distinction is purely for UX (which editor the
dashboard renders) and for documentation (mappings read $.payload.* vs
$.canonical.*).
The classifier is infer_entity_mode in
(internal plugsync tooling - see the source repo). Mode is derived, never persisted.
Decision rule
An entity is simple iff it has exactly one schema and that schema is named
hubspot. Otherwise it is federated.
| Entity schemas | Mode |
|---|---|
{"hubspot": ...} | simple |
{"hubspot": ..., "canonical": ...} | federated |
{"hubspot": ..., "compass": ...} | federated |
{"canonical": ...} | federated |
{"shopify": ...} (no hubspot) | federated |
The single non-hubspot case is intentionally classified federated: direct-mode UX requires a hubspot schema to write into, so the federated editor is the right surface for the operator to add the missing schemas.
When to choose which
Choose simple when:
- You have exactly one inbound source and you want it to write to HubSpot directly.
- All your field mappings can read
$.payload.*without intermediate shaping.
Choose federated when:
- Multiple sources feed the same entity and need a shared canonical representation.
- You need to transform inbound payloads into a
canonicalshape before writing to a target. - You’re sending data from HubSpot to a non-HubSpot system (outbound) and need a schema describing the target.
Dashboard affordance
The dashboard’s entity editor renders a single-schema simple-mode editor for
simple entities and a multi-tab federated editor for federated. A “Switch to
multi-system” button on the simple editor adds a canonical schema and
converts the entity to federated. There is no reverse “Switch to simple”
button - removing all non-hubspot schemas in the federated editor and
saving will cause infer_entity_mode to return simple on the next read.