Schema

This guide introduces you to the concept of schema. 

What is schema

Schema defines how raw records transform into structured items. It acts as a mapping layer that determines which record fields become item attributes, what data types those attributes should have, and how they should be named in downstream Bloomreach products. 

Each item type has its own schema and identifier settings. Mapping a field in one item type doesn't create an attribute in another.

Why is schema important

Schema gives you control over how your data appears in Bloomreach products without changing your source systems. 

Adjust field mappings, add new attributes, or change data types, then transform your existing records to generate updated items—all without re-importing data. Changing the schema reprocesses existing records into updated items.

Proper schema mapping ensures that Bloomreach products understand your data correctly and consistently.

Key components

Schema includes three key components: 

Item ID

The item identifier determines which record field becomes the unique ID for each item. By default, the system uses the record's ID, but you can choose any field from your records, like sku or product_id. This identifier must be stable, unique, and meaningful to your business.

Attribute types

Schema supports two types of attributes:

System attributes

Predefined fields with special meaning in Bloomreach products (like title, price, url). These enable core functionality like search, personalization, and product recommendations.

Custom attributes

Fields unique to your business that you define (like color_family, seasonal_collection, and sustainability). You specify their names, data types, and which record fields they map to.

Attribute data types

Every attribute has a data type. System attributes have predefined data types. Custom attributes use supported data types. Check the detailed guide on schema mapping. 

Override mappings

If the item type has a context, an attribute can also have an override mapping. It reads the attribute's value for each context value from the override data. Attributes without an override mapping use their base value. To add one, map schema attributes to override data.

Configure schema

To configure schema mappings in Data hub interface, see the detailed setup guide.

To understand how schema-generated items appear in Bloomreach products, review the items concept guide.

FAQs

Can I map multiple source fields to the same attribute?

Yes, with a custom expression. Record field mapping selects one source field. To combine several fields, write a custom expression in Data hub. If the item type has a context, an attribute can also have one override mapping, which reads one record field or JSON path from the override data.

What happens if I map a source field that doesn't exist in my records?

The schema accepts the mapping, so you can prepare schema configurations before data arrives. When a record doesn't contain the field, Data hub applies the attribute's empty value handling.

Do I need to map every field in my records?

No. You only map fields you want to appear as attributes in items. Unmapped fields remain in records but don't become item attributes accessible to Bloomreach products.

Can variants have different attributes than their parent product?

Yes. Variant-level attributes are independent of product-level attributes in Data hub. Each level has its own set of mapped fields.

For Search destinations, custom attributes have one effective configuration per attribute name. If the same custom attribute name is defined at both product and variant levels, Search uses the variant-level configuration for that custom attribute. Use distinct custom attribute names when product-level and variant-level custom values both need to be available in Search. System attributes follow their own Search destination behavior.

Next steps

Now that you understand schema configuration:

• Review items to see how schema-generated attributes appear as items.

• Learn about schema mapping. 

• Learn about records to understand the source data schema transforms.

• Monitor jobs to track schema reprocessing operations.

• Configure destinations to see how schema affects data in Search and Marketing.