Define custom attributes, custom object types, and site preferences for B2C Commerce using metadata XML. Use this skill whenever the user needs to add a field to products, orders, or customers, create a new custom object type, set up site preferences, or extend the B2C data model. Also use when they ask about system-objecttype-extensions.xml, custom-objecttype-definitions.xml, attribute groups in Business Manager, or data model definitions — even if they just say "add a field to products" or "I need a new object type".
Define custom attributes, custom object types, and site preferences for B2C Commerce using metadata XML. Use this skill whenever the user needs to add a field to products, orders, or customers, create a new custom object type, set up site preferences, or extend the B2C data model. Also use when they ask about system-objecttype-extensions.xml, custom-objecttype-definitions.xml, attribute groups in Business Manager, or data model definitions — even if they just say "add a field to products" or "I need a new object type".
Metadata Skill
This skill guides you through working with site metadata XML for Salesforce B2C Commerce, including custom attributes, custom objects, and site preferences.
Scope & grounding
This skill covers B2C Commerce metadata XML system (metadata.xsd namespace http://www.demandware.com/xml/impex/metadata/2006-10-31), including system-objecttype-extensions.xml, custom-objecttype-definitions.xml, and preferences.xml file structures. The examples show attribute types, enum value patterns, and Script API custom attribute access via dw.system.Site and ExtensibleObject.custom. Before answering questions that name specific B2C versions, XSD schema constraints, or emitting code the user will run, confirm current API shape and schema rules via b2c docs search and b2c docs read (CLI) or docs_search/docs_read (MCP). The canonical B2C Commerce documentation is the grounding source for metadata schema evolution, Script API signatures, and platform object types.
Canonical docs:
metadata - metadata XML schema and structure
dw.system.Site - Script API for site preferences
dw.system.SitePreferences - Script API for site preferences access
dw.object.CustomAttributes - Script API for custom attribute access
b2c-commerce/b2c-create-impex-folder-structure-ds - site archive folder structure
Illustrative list; confirm current platform object types with b2c docs read b2c-commerce/creatingcustombusinessobjectswithdemandwarebusinessmanager and Business Manager object reference.
Object Type
Use Case
Product
Product attributes
Order
Order metadata
Profile
Customer profile data
Basket
Cart data
SitePreferences
Site configuration
Category
Category attributes
Content
Content asset attributes
See System Objects Reference for more types. The full set of extensible system objects is defined by the B2C platform — check Business Manager and official docs for version-specific availability.
Attribute Types
Per metadata.xsd simpleType.AttributeType — confirm current schema with b2c docs schema metadata.
Type
Description
Example
string
Text (max 4000 chars)
SKU, descriptions
text
Long text (unlimited)
Rich content
int
Integer
Quantity, rank
double
Decimal
Percentage, weight
boolean
true/false
Flags
date
Date only
Birth date
datetime
Date and time
Timestamps
email
Email address
Contact email
password
Encrypted
API keys
html
HTML content
Rich text
enum-of-string
Single select
Status
enum-of-int
Numeric enum
Priority level
set-of-string
Multi-select
Tags
set-of-int
Numeric multi-select
Categories
image
Image reference
Thumbnails
Enum Value Definitions
Illustrative of enum structure; confirm current schema ordering constraints with b2c docs schema metadata.
Element order matters. The metadata.xsd schema requires <display> before <value> in each <value-definition> — see b2c docs schema metadata for current schema constraints.
<?xml version="1.0" encoding="UTF-8"?><metadataxmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31"><custom-typetype-id="StoreLocations"><display-namexml:lang="x-default">Store Locations</display-name><descriptionxml:lang="x-default">Physical store information</description><staging-mode>source-to-target</staging-mode><storage-scope>site</storage-scope><key-definitionattribute-id="storeId"><display-namexml:lang="x-default">Store ID</display-name><type>string</type><min-length>1</min-length></key-definition><attribute-definitions><attribute-definitionattribute-id="storeName"><display-namexml:lang="x-default">Store Name</display-name><type>string</type><mandatory-flag>true</mandatory-flag></attribute-definition><attribute-definitionattribute-id="latitude"><display-namexml:lang="x-default">Latitude</display-name><type>double</type></attribute-definition><attribute-definitionattribute-id="longitude"><display-namexml:lang="x-default">Longitude</display-name><type>double</type></attribute-definition><attribute-definitionattribute-id="phone"><display-namexml:lang="x-default">Phone</display-name><type>string</type></attribute-definition><attribute-definitionattribute-id="isActive"><display-namexml:lang="x-default">Active</display-name><type>boolean</type><default-value>true</default-value></attribute-definition></attribute-definitions><group-definitions><attribute-groupgroup-id="StoreInfo"><display-namexml:lang="x-default">Store Information</display-name><attributeattribute-id="storeId"system="true"/><attributeattribute-id="storeName"/><attributeattribute-id="latitude"/><attributeattribute-id="longitude"/><attributeattribute-id="phone"/><attributeattribute-id="isActive"/></attribute-group></group-definitions></custom-type></metadata>
Site Preferences
Site-specific configuration via custom attributes on SitePreferences.
Metadata (system-objecttype-extensions.xml)
<?xml version="1.0" encoding="UTF-8"?><metadataxmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31"><type-extensiontype-id="SitePreferences"><custom-attribute-definitions><attribute-definitionattribute-id="enableFeatureX"><display-namexml:lang="x-default">Enable Feature X</display-name><type>boolean</type><default-value>false</default-value></attribute-definition><attribute-definitionattribute-id="apiEndpoint"><display-namexml:lang="x-default">API Endpoint</display-name><type>string</type></attribute-definition><attribute-definitionattribute-id="maxItemsPerPage"><display-namexml:lang="x-default">Max Items Per Page</display-name><type>int</type><default-value>20</default-value></attribute-definition></custom-attribute-definitions><group-definitions><attribute-groupgroup-id="CustomSettings"><display-namexml:lang="x-default">Custom Settings</display-name><attributeattribute-id="enableFeatureX"/><attributeattribute-id="apiEndpoint"/><attributeattribute-id="maxItemsPerPage"/></attribute-group></group-definitions></type-extension></metadata>
Values (sites/MySite/preferences.xml)
Preferences can be set per instance type (development, staging, production) or for all instances:
<?xml version="1.0" encoding="UTF-8"?><preferencesxmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31"><custom-preferences><all-instances><!-- Values that apply to all instance types --><preferencepreference-id="maxItemsPerPage">25</preference></all-instances><development><!-- Development-specific values --><preferencepreference-id="enableFeatureX">true</preference><preferencepreference-id="apiEndpoint">https://dev-api.example.com/v1</preference></development><staging><preferencepreference-id="enableFeatureX">true</preference><preferencepreference-id="apiEndpoint">https://staging-api.example.com/v1</preference></staging><production><preferencepreference-id="enableFeatureX">false</preference><preferencepreference-id="apiEndpoint">https://api.example.com/v1</preference></production></custom-preferences></preferences>
Access in Code
Illustrative code; confirm current API signatures and return types with b2c docs read dw.system.Site.
// See dw.system.Site Script API docs for full method signatures and return typesvarSite = require('dw/system/Site');
var enableFeatureX = Site.current.getCustomPreferenceValue('enableFeatureX');
var apiEndpoint = Site.current.getCustomPreferenceValue('apiEndpoint');
var maxItems = Site.current.getCustomPreferenceValue('maxItemsPerPage');
Attribute Definition Options
Illustrative of available flags; confirm current schema elements and deprecation status with b2c docs schema metadata.
<attribute-definitionattribute-id="myAttribute"><display-namexml:lang="x-default">Display Name</display-name><descriptionxml:lang="x-default">Description for BM tooltip</description><type>string</type><localizable-flag>false</localizable-flag><site-specific-flag>false</site-specific-flag><mandatory-flag>false</mandatory-flag><searchable-flag>false</searchable-flag><visible-flag>true</visible-flag><externally-managed-flag>false</externally-managed-flag><order-required-flag>false</order-required-flag><min-length>0</min-length><field-length>256</field-length><unitxml:lang="x-default">kg</unit><default-value>default</default-value></attribute-definition>
Flag
Purpose
localizable-flag
Can have different values per locale
mandatory-flag
Required in BM
externally-managed-flag
Read-only in BM
visible-flag
Shown in BM
site-specific-flag
Different value per site
order-required-flag
Required for order export
searchable-flag
Indexed for search (deprecated per metadata.xsd — use search2.xsd SearchableAttributes instead)
Best Practices
Use attribute groups to organize in Business Manager
Prefix custom attributes with organization name (e.g., acme_myAttribute)
Set externally-managed for data imported from external systems
Use enums over strings for controlled vocabularies
Document with descriptions - they appear as tooltips
Quick Reference
For canonical documentation, see the Scope & Grounding section above. The files below are derived quick-reference summaries.
