Schema mapping

👍

Welcome note

Data hub is our new upgraded platform, which we rolled out in August 2025. It offers a single unified integration for passing your data through to your Bloomreach products.

You have access to Data hub if you've implemented with Bloomreach after August 2025.

Customers who have implemented before August 2025 should follow the existing documentation for Engagement, Discovery, and Clarity.

This guide introduces you to the concept of schema mapping. 

What is schema mapping

Schema mapping is the process of connecting data from your source systems to Bloomreach's Data hub structure. It determines which information from your business data flows into Bloomreach products and how that data translates into usable attributes.

Why is schema mapping important

Effective schema mapping ensures you pass only relevant data to Bloomreach while maintaining flexibility for future needs. Planning your schema mapping strategy before implementation leads to more efficient application performance and easier data management over time.

How schema mapping works

The most effective approach to schema mapping follows a 3-phase strategy:

1. Import all your data at once: Start with a complete dataset rather than adding information piecemeal over time. 
2. Map important information to system attributes: According to your business analysis objectives, identify and map the most critical data points from your source to Bloomreach's system attributes. 
3. Add custom attributes and detailed mappings: With your base mapping established, add custom attributes and map additional data whenever new requirements emerge. 

This methodology offers 2 key advantages: improved application-level performance and the ability to map new data points from your existing import source without reimporting.

Key concepts

Attributes

Attributes connect relevant data from your import source to the Data hub schema. Each attribute includes a:

• Name
• Type classification (system or custom)
• Data type (string, integer, and more)
• Mapping configuration that determines how values are assigned

Bloomreach supports two attribute types:

• System attributes: Predefined standard fields such as title, URL, and price. These represent the minimum required attributes and map directly to reserved attributes in each Bloomreach application.
• Custom attributes: Fields that you define for more complex data needs, such as compound calculations from multiple source data points.

Attribute names

Within the Data hub, each attribute requires a unique name. System attributes use predefined names, while you provide names for custom attributes.

Naming requirements

• Must use UTF-8 encoding.
• Must be fewer than 128 characters.
• Can't include control characters.
• May have additional restrictions depending on specific Bloomreach application use cases.

Uniqueness rules

System attribute names are unique within the system attributes list, and custom attribute names are unique within the custom attributes list. This means Bloomreach's system attribute for price differs from a custom attribute also named price.

Handling name conflicts

When a custom attribute shares a name with a system attribute, Bloomreach automatically prefixes the custom attribute with "main" in the Bloomreach application destinations. For example, if you create a custom attribute named price, it becomes main.price in the application destination, while the system attribute remains price. Applications that use system attributes never reference custom attributes with the same name.

Application destination mapping

System attributes map directly and automatically to each Bloomreach application's reserved attributes. For specific mapping details, see the Engagement Reserved Attributes and Discovery Reserved Attributes documentation.

Note that some system attributes don't map one-to-one across applications. Specific examples include:

• Engagement mappings: launch_date maps to date_added, and category_paths maps to multiple category-related attributes.
• Discovery mappings: original_price maps to price, and active maps to availability.

Review the full destination mapping list for specifics on how each system attribute behaves within each Bloomreach application.

Attribute data types

Every attribute has a data type. System attributes use predefined data types, while custom attributes can use any of the following supported types:

• String: Text values.
• Integer: Whole numbers.
• Float: Decimal numbers.
• Boolean: True or false values.
• List of Strings: Multiple text values.
• List of Integers: Multiple whole numbers.
• List of Floats: Multiple decimal numbers.
• Date: Date values.
• DateTime: Date and time values.
• URLs: Web addresses

Each Bloomreach application can use these data types. However, some applications may cast certain data types differently. For example, a DateTime custom attribute becomes a Text type in Discovery. 

Type compatibility

When Data hub evaluates a mapping, the extracted value must be compatible with the attribute's data type. If there's a type mismatch, Data hub ignores the attribute for that item unless you've configured different error handling, such as failing the update on errors.

Attribute mapping

Defining an attribute doesn't automatically populate it with values. You must configure a mapping that specifies how to set attribute values from the data in your records and fields.

Mapping types

Each mapping has a type and a value. Bloomreach supports 2 mapping types.

Field mapping

Field mapping uses a field name from your record to set the attribute value. For example, if you're mapping the price system attribute and set the value to display_price, Data hub looks for the display_price field in your record to populate the attribute.

Cross-level field access

When mapping attributes, you can access fields from different levels of your data hierarchy:

• Product-level attributes: Can access variant-level fields when building product attributes. When a product searches for data in variants, it needs to aggregate the values, and you can specify the aggregation function, such as random, min, max, and so on. 
• Variant-level attributes: Can access parent product-level fields when building variant attributes.

This cross-level access is useful when creating attributes that need to combine or reference data from multiple levels, such as using product-level default values for variant-level attributes.

Empty value handling

When mapping encounters empty, null, or missing values, you can configure specific behaviors:

• Set to empty value: Accept the empty state and create the attribute with no value.
• Fall back to another field mapping: Use an alternative field as the source. This is useful for variant-level attributes that should inherit product-level defaults when variant-specific values are missing.
• Fall back to a constant value: Use a predefined fallback value when the source field is empty.
• Skip the attribute: Don't create the attribute for this item. An attribute warning will be present on the item to indicate the missing attribute.
• Skip the item: Don't build the item at all. This ensures only items with complete required data are created. Useful when you need to guarantee all items have values from the source.
• Fail the job completely: Stop processing and fail the entire update job. This provides strict data quality enforcement and prevents any issues from reaching downstream applications.

Choose your error handling strategy based on your data quality requirements and business logic needs.

Category paths system attribute

The category paths system attribute manages hierarchical category structures for your products. This attribute works with both product-level and variant-level records, allowing you to define where products belong in your catalog taxonomy.

Application-specific behavior 

Category paths is one of the system attributes that doesn't map one-to-one across Bloomreach applications:

• In Engagement: The category_paths attribute maps to multiple category-related attributes in the catalog, allowing for complex category hierarchies and relationships.
• In Discovery: Category paths maintain their structure but may be processed differently depending on your catalog configuration.

The category paths attribute supports multiple paths per product, enabling products to appear in multiple categories simultaneously. Review the application-specific documentation for details on formatting and hierarchy depth limitations.