Attribute definitions

Before importing product data, Enhance needs a definition for every structured product attribute.

We can accept the definitions in any structured format, including CSV, XML, JSON, or JSONL. JSON-like formats are preferred because they preserve data types, lists, units, and allowed values without ambiguity.

Required information

Field	Required	Description
id	Yes	A unique and stable identifier from your PIM or source system, for example product_weight. Use the same identifier consistently in all supplied files.
display_name	Yes	The human-readable name, for example Product weight.
type	Yes	The kind of value stored by the attribute: string, number, or enum.
is_list	Yes	Whether one product can have one value or multiple separate values for the attribute.
description	No	Additional information about the meaning of the attribute.
allowed_units	No	Units accepted for a number attribute, for example ["kg", "g"]. For string attributes, units are presentation metadata shown separately in Studio and are not part of the enhanced value.
allowed_enum_values	For enum attributes	The accepted values for an enum attribute. Values must be unique. Large value lists may be supplied in a separate file.

Data types

String

Use string for arbitrary text.

Examples:

Potential attribute	Example value
Compatibility	Windows 11 or later; USB-C connection required
Material composition	80% cotton, 20% recycled polyester
Package contents	Base unit with mounting bracket and 2 m cable
Care instructions	Wipe with a damp cloth; do not immerse in water

For a string attribute, allowed_units is presentation metadata. The enhanced value contains only the text, such as "2-6" or "5+"; Studio displays the configured unit, such as players, separately.

Number

Use number for an attribute that contains one numeric value, such as weight or length. If the attribute has a unit, provide the accepted units in allowed_units.

Enum

Use enum when the value must be selected from a predefined list.

For example, if the allowed values are Black, White, and Blue, a product may use Black but not an unlisted value such as Red.

Single and multiple values

Some attributes contain a list of values. Common examples are the colors or materials of a product when more than one value can apply.

is_list defines the expected structure of the attribute in Enhance:

• Use false when the attribute contains exactly one value:

  { "primary_color": "Black" }

• Use true when the attribute can or should contain a list of values:

  { "colors": ["Black", "Silver"], "materials": ["Steel", "Plastic"] }

Set is_list to true whenever multiple values are valid for the attribute, even if some products have only one value.

Example

[
	{
		"id": "weight",
		"display_name": "Weight",
		"type": "number",
		"is_list": false,
		"description": "The total product weight excluding packaging",
		"allowed_units": ["kg", "g"]
	},
	{
		"id": "color",
		"display_name": "Color",
		"type": "enum",
		"is_list": false,
		"description": null,
		"allowed_enum_values": ["Black", "White", "Blue"]
	},
	{
		"id": "package_contents",
		"display_name": "Package contents",
		"type": "string",
		"is_list": true,
		"description": null
	},
	{
		"id": "compatibility",
		"display_name": "Compatibility",
		"type": "string",
		"is_list": false,
		"description": null
	}
]

Providing allowed values separately

Allowed values can normally be included directly in an enum attribute definition:

{
	"id": "color",
	"display_name": "Color",
	"type": "enum",
	"is_list": false,
	"description": null,
	"allowed_enum_values": ["Black", "White", "Blue"]
}

If the lists are large or already maintained separately, they can instead be provided in a separate file. Each entry must connect one value to the corresponding attribute using attribute_id:

[
	{
		"attribute_id": "color",
		"value": "Black"
	},
	{
		"attribute_id": "color",
		"value": "White"
	},
	{
		"attribute_id": "color",
		"value": "Blue"
	}
]

Every entry must reference an existing attribute ID. Values for the same attribute must be unique.