HomeData hubOther resources
Guides

Configure schema

Suggest Edits

👍

Data hub rollout

Data hub provides new unified API integration methods for sending data to multiple Bloomreach products. Access is being rolled out in phases. For new implementations, we recommend using Data hub where available. Existing product-specific integrations remain fully supported for Engagement, Discovery, and Clarity.

Map your raw record fields to meaningful attributes so the system can create items from them.

Prerequisites

Knowledge

  • Understanding of item collection concepts.
  • Understanding of which record fields should map to product-level vs. variant-level attributes.
  • Knowledge of appropriate data types for your attributes (string, number, boolean, array).
  • Knowledge of schema mapping.

Process

Steps to configure schema

The following steps apply to both product and variant attribute mappings.

1. Navigation

  1. Go to Data hub > Items in your Bloomreach workspace.
  2. Locate and open the existing item collection from the item collections listing page.
  3. Click the Schema tab.

2. Set item identifier

This defaults to Record ID. Alternatively, you can choose a Record field or JSON path as the item ID.

Record field

  • Field name: Enter the name of your source field.

  • Record level: Select which level (product or variant) of your data hierarchy contains this field.

JSON path

Specify the path to nested objects and arrays using JMESPath syntax. A few common patterns include:

  • product.name: nested field selection.
  • attributes.dimensions.height: deeper nesting inside objects.
  • images[0].url: pick a specific array element.
  • variants[].sku: project all values from an array.
  • variants[?available==true].sku: filter by boolean flag before projection. This returns an array. If you expect a single result from the filter and select the first value, use variants[?available==true].sku | [0].
  • variants[?size=='XL'].price: filter by string and return matching prices.

Validate expressions with a JMESPath tool to ensure the syntax matches your record structure.

❗️

Important

For JSON Path, if the path is invalid, can't be found, or the path results in a literal null value, it is treated as a null value.

Fallback behavior

Choose the fallback behavior and define what happens when the specified field value is missing:

  • Fallback to record ID (default): Uses the record ID if your custom field is empty.
  • Skip updates for related item: Ignores records without the custom field value.
  • Stop job execution (job failure): Fails the job if any record is missing the field value.

3. Add attributes

Click + New attribute. You can add either system or custom attributes.

System attributes

Add individual system attributes

Enter or select a system attribute from the Attribute name dropdown.

Bulk add system attributes

  1. Click the dropdown next to the + New attribute button and click Bulk add system attributes.

  2. Bulk select and map system attributes to source fields from your records (like title, price, url). Click Apply selection.

Proceed with mapping. Review the guide on mapping category data.

Custom attributes

  1. Enter or select a custom attribute for any fields unique to your business (like color_family or custom_level).

  2. Choose a Data type, and proceed with mapping.

Custom attributes namespacing

When custom attributes have the same name as system attributes, they receive a namespace prefix to prevent collisions when they sync with destinations.

Example

Schema: Custom attribute named color

Engagement catalog: Appears as main.color

Discovery catalog: Appears as main.color

The main namespace ensures your custom color attribute doesn't conflict with any system color attribute. System attributes map directly without the namespace prefix.

4. Configure attribute mapping

Choose one of the three mapping options: Record field, JSON path, or Custom expression.

Record field

Enter the exact field name in the source record. Set the source value from the product or variant source level.

JSON Path

Specify the path to nested objects and arrays using JMESPath syntax. For example, get dimension.height or image[0].url. Set the source value from the product or variant source level.

Custom expression

Write custom expressions in Python-like syntax to combine fields and apply transformations.

Apply aggregation methods

When mapping a product-level attribute from variant-level fields, you can specify how to aggregate these values based on the business need:

  • Apply RANDOM value: Collects all variant values, then picks one at random. Fails if no values exist. Supports all data types.

  • Apply MAX value: Converts variant values to numbers and returns the largest. Fails if values can't be converted to numbers or none are found.

  • Apply MIN value: Converts variant values to numbers and returns the smallest. Fails if values can't be converted to numbers or none are found.

  • Apply SUM of all values: Converts each variant value to a number (or list of numbers), adds them together, and returns the total as a float. Fails if any value can't be converted.

  • Apply AVERAGE of all values: Converts values to numbers, sums them, and divides by the total count. Requires at least one numeric value.

  • Apply COUNT of all values: Counts distinct values across all variants (ignoring duplicates). Supports all data types.

  • AGGREGATE all values: Collects every successful variant value into a single list. Use this when the parent attribute expects a list aggregated from variant lists or scalars. Fails if no variant produces a value.

Apply value transformation (optional)

After mapping, optionally apply transformations to the value.

  • String split: Splits a string into a list using your specified delimiter. Example: with delimiter |, the input red|green|blue becomes ["red", "green", "blue"]. Fails if the delimiter is missing or not a string, or if the input isn't a string.

  • Trim whitespace: Removes leading and trailing whitespace from a string or from every element in a list of strings. Example: [" red ", "blue"] becomes ["red", "blue"]. Fails if the input isn't a string or a list of strings.

  • Uppercase: Converts a string or all strings in a list to uppercase. Case conversion is locale-insensitive. Example: sku-1 becomes SKU-1.

  • Lowercase: Converts a string or all strings in a list to lowercase. Example: ["ABC", "Def"] becomes ["abc", "def"].

Handle exceptional scenarios

If the mapping returns a null, empty, or missing value, specify how to handle the exception:

  • Fall back to value: Specify a constant default value to use if mapping fails.

  • Fall back to field: Define a secondary mapping to try if the first fails. For example, if a variant price is missing, look for a product-level price.

  • Skip updates for this attribute: Don’t create or update the attribute for the item if mapping fails.

  • Skip updates for related item: Don’t create or update the entire item if mapping fails for this attribute.

  • Stop job execution: Immediately fail the job if mapping fails. You must fix the data and rerun.

Not all mapping types support all five options. For example, fallback to another field mapping isn't always available to prevent infinite loops. These mapping and failure handling options apply to both custom and system attributes, and to both products and variants.

Attribute status

Check the attribute status using the colored indicators:

  • Green: Attribute mapped and published.
  • Orange: Attribute locally drafted but not saved.
  • Yellow: Attribute isn’t mapped.

5. Save changes

Click Save changes. Repeat the same process for variant attributes by clicking the Variant level tab.

Data hub reprocesses your data to generate items based on the new mappings. Wait for the items update job to complete.

Next step

Verify items.

Updated about 5 hours ago