link

Version: v2 Scope: per-tenant+store Owning service: link-registry

A link is the central binding record of the platform: it joins one or more items to one or more ESLs and specifies how the resulting label should be rendered. Every time a shelf label needs to show a price, a product name, or any other item attribute, there is a link record that says "ESL with barcode X, in store Y, shows item Z using design D." The link is what makes the system dynamic — changing item prices or swapping designs triggers downstream projections (studiolink, ecclink) to be re-evaluated without touching the link itself.

ID pattern

t/{tenantid}/s/{storeid}/links/{linkid}

• t/{tenantid} — tenant namespace
• s/{storeid} — store within the tenant
• links/{linkid} — the platform-assigned link identifier

Schema

Top-level fields

Field	Type	Description
id	string	Primary ID
location	string	Physical shelf location annotation. Examples: "Aisle 5", "Shelf B12", "End Cap". May be displayed on the label

Sub-messages

Esl

Field	Type	Description
barcode	string	ESL barcode (hardware identifier)
esltype_id	string	Short ESL type ID

LinkedItem

Field	Type	Description
item_id	string	The item whose data drives rendering (price, name, etc.). Short format — tenant/store implicit from the link ID. Example: "4006381333931"
linked_item_id	string	The identifier used during linking (usually identical to item_id, but may be a SIC). Required
facings	string	Number of facings for this item; may appear on the label. Examples: "3", "Up"

---

oneof system

V2 uses a top-level system discriminator. Every link belongs to exactly one rendering pipeline.

Note: link.v1 used a flat three-way oneof variant that mixed ECC and Studio cases — see the v1 footnote at the bottom of this page.

oneof variant

Ecc branch — ECC-model-based rendering

Ecc.Single (single item, single ESL)

Field	Type	Description
esl	Esl	The linked ESL
eccmodel_id	string	Short ECC model ID
item	LinkedItem	The single linked item

Ecc.MultiItem (multi-item, single ESL)

Field	Type	Description
esl	Esl	The linked ESL
eccmodel_id	string	Short ECC model ID
items	repeated LinkedItem	Items ordered by display position; omit trailing unlinked positions

Studio branch — Studio-design-based rendering

Studio.Single (single item, single ESL)

Field	Type	Description
esl	Esl	The linked ESL
forced_design_id	string	Optional short design ID
item	LinkedItem	The single linked item

Studio.FloatingCanvas (single item, multiple ESLs)

Field	Type	Description
esls	repeated Esl	All ESLs on the canvas; first entry's barcode must match the link ID's barcode
forced_design_id	string	Optional short canvas design ID
item	LinkedItem	The item driving the canvas

---

Aliases

by_item

Pattern: t/{tenantid}/s/{storeid}/items/{itemid}/links/{linkid}

Allows retrieving or listing all link records that reference a particular item. Covers all variants: - ecc.single.item.item_id - studio.single.item.item_id - studio.floating_canvas.item.item_id - ecc.multi_item.items[].item_id (one alias entry per item)

by_storeesl

Pattern: t/{tenantid}/s/{storeid}/esls/{barcode}/link

Allows looking up the single active link for a specific ESL. An ESL may only be assigned to one link at a time, so this is a point lookup. Covers all variants: - ecc.single.esl.barcode - studio.single.esl.barcode - studio.floating_canvas.esls[].barcode - ecc.multi_item.esl.barcode

Consumed by

Service	Why
studio-link-evaluator	Subscribes to link.v2; evaluates the link against item data and communication packs to produce a studiolink projection
ecclink-projector	Projects link.v2 ECC-branch records into ecclink records consumed by ecc-image-render-service
link-registry	Owns the link records; provides CRUD and handles the alias index

Related DTOs

• storeesl — the ESL referenced in every link variant; looked up via by_storeesl alias
• storeeslstatus — lifecycle state of the ESLs referenced in a link
• studiolink — Studio rendering projection derived from the Studio branch by studio-link-evaluator
• ecclink — ECC rendering projection derived from the ECC branch by ecclink-projector

---

Footnote: link.v1 (deprecated)

link.v1 used a flat oneof variant with three cases (Single, MultiItem, FloatingCanvas) that mixed ECC and Studio rendering in a single union. Single.forced_design_id and Single.eccmodel_id were a oneof design_source inside the same variant, which created ambiguity: callers had to inspect the inner field to determine which rendering pipeline owned the link.

V2 resolves this with a top-level oneof system { Ecc ecc; Studio studio; }. Callers know immediately which pipeline owns the link. V1 also had by_design and by_canvasdesign aliases that leaked renderer knowledge into the core link DTO; those moved to studiolink.

No new link.v1 records are written. All new links are v2. See ADR-003.