Design your model

Attributes and attribute groups

Create the fields your products can have, choose the right type, and arrange them so the editing screen makes sense.

An attribute is one field a product can have. Everything else in the model sits on this layer, so be deliberate about types and options.

Take the fitting 4711-A. Its thread size, its material and its pressure rating are three attributes. Whether a buyer can filter by thread size, whether the material reads the same on 1,400 products, and whether the pressure rating converts to psi for a customer in the US are all decided by how those three attributes are typed. Nothing you do later on the product can repair a wrong type.

Before you start: have the attribute table from Plan your data model in front of you. Creating attributes ad hoc as you think of them is how catalogs end up with material, werkstoff and material_neu.

Choosing a type

The type is fixed once data exists, so choose carefully. The left column is the name this guide uses; the second is what the Type field in the Cockpit offers.

Type	Cockpit type	Use it for	Do not use it for
Text	`text`	Short prose: name, subtitle	Facts a buyer filters by
Textarea	`textarea`	Long prose: description, application notes	Anything structured
Number	`number`	Counts and unitless quantities	Anything with a unit; use Measurement
Measurement	`metric`	Physical quantities: length, weight, pressure	—
Boolean	`boolean`	A real yes/no: `rohs_compliant`	Three-state facts ("unknown" is not false)
Single-select	`select`	One value from a fixed list: material, colour	Values that keep growing arbitrarily
Multi-select	`multiselect`	Several from a fixed list: certifications	—
Date	`date`, `datetime`	Availability dates, revision dates	—
Price	`price_collection`	Attribute-level prices	Your sales prices; those live in Pricing
Reference	`reference_entity`, `reference_entity_collection`	A pointer to one or several records of a reference entity	Repeated free-text names
Asset	`asset_collection`	Pointers to managed assets	—

The Cockpit also lists identifier and table. Leave them alone unless an import format asks for them.

Number vs. Measurement. If the value has a unit, use Measurement. Storing 10 as a number and "mm" somewhere else means nothing can convert it, compare it, or display it correctly for a market that uses inches.

Create an attribute

Go to PIM › Data model › Attributes.
Select New attribute.
Enter a Code. This is the permanent identifier: lowercase, no spaces, and it cannot be changed later. Use thread_size, not Thread Size or attr_17.
Choose the Type from the table above.
Leave Entity type on Product. The other values (Reference entity, Asset, Category) are for attributes that belong to those objects, and then Entity ref names which one.
Choose an Attribute group. This decides where the field appears on the product editing screen. See below.
Set the flags:
- Localizable: one value per language. Prose yes, numbers no.
- Scopable (per channel): one value per channel. Use sparingly.
- Unique: no two products may share the value. Right for ean, wrong for almost everything else.
- Filterable (facet): buyers can narrow by it. Set this on every fact a buyer would choose by.
- Usable in grid: you can see it in the product list. Set it on the handful you work with daily.
Add Validation where it helps: Minimum length, Maximum length and a Pattern for text, Minimum and Maximum for numbers, Maximum file size for assets. Validation at this level is far cheaper than cleaning bad data later.
Fill the type-specific Config: the Metric family and default Unit for a measurement, the Reference entity for a reference, the Asset family and Allowed extensions for an asset attribute.
Enter the Labels (i18n) and save.

Add options to a select attribute

A single- or multi-select attribute is only useful once it has options.

Open the attribute and go to Options.
Select Add option and enter a Code and the Labels (i18n) per language. A colour option can also carry a Swatch with a Hex colour.
Order them with Sort. This is the order buyers see in a filter, so put it in a sensible sequence (sizes ascending, not alphabetical).

Codes are what get stored and exported; labels are what people see. v4a with the label "Stainless steel V4A" means you can rename the label in three languages without touching a single product.

Attribute groups

An attribute group is purely about the editing experience: it decides which fields sit together in which tab on the product screen.

Good groups follow how people work, not how the database looks:

Marketing: name, description, application notes
Technical data: the facts a buyer filters by
Logistics: weight, dimensions, packaging unit, customs tariff number
Commercial: manufacturer, brand, lifecycle status
Media: images, datasheets, drawings

To create one, go to PIM › Data model › Attribute groups, select New group, and give it a Code, Labels (i18n) and a Sort position.

Groups matter more than they sound. A product screen with sixty ungrouped fields is one nobody maintains carefully. The same sixty fields in five labelled tabs get filled in properly.

Changing an attribute later

Change	Effect on existing data
Labels, Sort, Attribute group, Filterable, Usable in grid, adding options	Safe. Nothing stored changes.
Validation rules	Careful. Existing values are not re-validated, so you can end up with data that would no longer be accepted.
Type, Localizable, Scopable, Unique	A migration, not a toggle. Changing these on an attribute that already holds data changes the shape or the storage location of every stored value. Plan it. Do not click it on a Friday.
Code	Cannot be changed. Create a new attribute and move the data.

Families — decide which products need which attributes.

Edit this page

Plan your model

The six decisions to make on paper before you create your first attribute, and the order to make them in.

Families

Define which attributes a kind of product has, which are required, and for which channels.