Dynamic Blocks

Dynamic blocks are per-product rich content — grids of image, video, 3D, and text elements rendered on the B2B product detail page. They are stored on the product document as a dynamic_blocks array (Mongo only; excluded from the Solr index) and attached to the storefront response by a gated enrichment step. Each block belongs to one language.

Where the field goes

On import, add dynamic_blocks to any product in the products[] array:

{
  "source_id": "<your-source-id>",
  "products": [
    {
      "entity_code": "<your-product-code>",
      "dynamic_blocks": [ /* blocks — see schema below */ ]
    }
  ]
}

Language rules

Replace + validation semantics

Block schema

Field	Type	Required	Description
`id`	`string`	Required	Stable, non-empty (e.g. a UUID).
`lang`	`string`	Required	A tenant-enabled, lowercase language code (see above).
`title`	`string`	Optional	Heading shown above the grid, in `lang`.
`section`	`1 \| 2 \| 3 \| 4`	Required	Page zone the block renders into.
`order`	`number`	Required	Sort order within (section, lang).
`columns`	`integer 1–8`	Required	Elements per row; the list wraps into rows.
`is_active`	`boolean`	Required	false hides the block without deleting it.
`elements`	`BlockElement[]`	Required	Ordered elements, ≤ 24 per block.

Element schema

Every element has id (non-empty string) and kind ("image" | "video" | "3d" | "text"), plus:

Field	Type	Required	Description
`media`	`object`	Optional	Required for image/video/3d. { url, cdn_key?, is_external_link?, alt? }. Forbidden on text.
`media.url`	`string`	Required	Non-empty safe URL: http(s) absolute or site-relative '/…'. No javascript:/data:/'//'.
`text`	`string`	Optional	Required for kind 'text' (non-empty). Forbidden on media kinds.
`description`	`string`	Optional	Optional caption in the block's lang.
`link`	`object`	Optional	Optional { href (safe URL), new_tab (boolean) } wrapping the element.

Limits: ≤ 20 blocks per product, ≤ 24 elements per block.

Example

{
  "id": "blk-hero-it",
  "lang": "it",
  "title": "Caratteristiche",
  "section": 1,
  "order": 0,
  "columns": 2,
  "is_active": true,
  "elements": [
    {
      "id": "el-img-1",
      "kind": "image",
      "media": { "url": "https://cdn.example.com/p/feature-1.jpg", "alt": "Dettaglio" },
      "link": { "href": "https://www.example.com/scheda", "new_tab": true }
    },
    { "id": "el-txt-1", "kind": "text", "text": "Materiali ad alta resistenza." }
  ]
}