b2c-metadata

What this skill does

# Metadata Skill

This skill guides you through working with site metadata XML for Salesforce B2C Commerce, including custom attributes, custom objects, and site preferences.


## Overview

Metadata defines the structure of your B2C Commerce data:

| Metadata Type | Purpose |
|---------------|---------|
| **System Object Extensions** | Add custom attributes to Products, Orders, Customers, etc. |
| **Custom Objects** | Define entirely new data types |
| **Site Preferences** | Site-specific configuration values |

## Site Archive Structure

Metadata is organized in site archives:

```
/site-archive
    /meta
        system-objecttype-extensions.xml    # Custom attributes on system objects
        custom-objecttype-definitions.xml   # Custom object definitions
    /sites
        /MySite
            preferences.xml                 # Site preferences
```

## System Object Extensions

Add custom attributes to existing system objects.

### Basic Structure

```xml
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="myCustomAttribute">
                <display-name xml:lang="x-default">My Custom Attribute</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>false</externally-managed-flag>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="MyCustomGroup">
                <display-name xml:lang="x-default">My Custom Group</display-name>
                <attribute attribute-id="myCustomAttribute"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>
```

### Common System Objects

| 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 |

### Attribute Types

| 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

Enum types (`enum-of-string`, `enum-of-int`, `set-of-string`, `set-of-int`) require `value-definitions` with **display/value pairs**:

> **Element order matters.** Inside each `<value-definition>`, the `<display>` element must come **before** `<value>`. The `metadata.xsd` schema enforces this strict ordering — putting `<value>` first fails site import validation with `cvc-complex-type.2.4.d: Invalid content was found starting with element 'display'`.

```xml
<attribute-definition attribute-id="warrantyType">
    <display-name xml:lang="x-default">Warranty Type</display-name>
    <type>enum-of-string</type>
    <mandatory-flag>false</mandatory-flag>
    <value-definitions>
        <value-definition>
            <display xml:lang="x-default">No Warranty</display>
            <value>none</value>
        </value-definition>
        <value-definition>
            <display xml:lang="x-default">Limited Warranty</display>
            <value>limited</value>
        </value-definition>
        <value-definition>
            <display xml:lang="x-default">Full Warranty</display>
            <value>full</value>
        </value-definition>
    </value-definitions>
</attribute-definition>
```

| Element | Purpose |
|---------|---------|
| `<display>` | Human-readable label shown in Business Manager (must appear first) |
| `<value>` | The stored/API value (use lowercase, no spaces) |

## Product Custom Attribute Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <!-- Simple string attribute -->
            <attribute-definition attribute-id="vendorSKU">
                <display-name xml:lang="x-default">Vendor SKU</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>true</externally-managed-flag>
            </attribute-definition>

            <!-- Enum (dropdown) attribute -->
            <attribute-definition attribute-id="productCondition">
                <display-name xml:lang="x-default">Product Condition</display-name>
                <type>enum-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <display xml:lang="x-default">New</display>
                        <value>new</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Refurbished</display>
                        <value>refurbished</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Used</display>
                        <value>used</value>
                    </value-definition>
                </value-definitions>
            </attribute-definition>

            <!-- Boolean attribute -->
            <attribute-definition attribute-id="isHazardous">
                <display-name xml:lang="x-default">Hazardous Material</display-name>
                <type>boolean</type>
                <mandatory-flag>false</mandatory-flag>
                <default-value>false</default-value>
            </attribute-definition>

            <!-- Multi-select attribute -->
            <attribute-definition attribute-id="productFeatures">
                <display-name xml:lang="x-default">Product Features</display-name>
                <type>set-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <display xml:lang="x-default">Waterproof</display>
                        <value>waterproof</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Recyclable</display>
                        <value>recyclable</value>
                    </value-definition>
                </value-definitions>
            </attribute-definition>
        </custom-attribute-definitions>

        <group-definitions>
            <attribute-group group-id="CustomProductInfo">
                <display-name xml:lang="x-default">Custom Product Information</display-name>
                <attribute attribute-id="vendorSKU"/>
                <attribute attribute-id="productCondition"/>
                <attribute attribute-id="isHazardous"/>
                <attribute attribute-id="productFeatures"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>
```

## Custom Object Definitions

Create entirely new data types.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <custom-type type-id="StoreLocations">
        <display-name xml:lang="x-default">Store Locat