Форматы YML и CSV

  1. Формат YML
  2. Текстовый формат

Формат YML

Стандарт YML (Yandex Market Language) разработан Яндексом и основан на стандарте XML. Формат YML предоставляет больше возможностей и преимуществ, чем форматы XLS, CSV.

Требования к YML‑файлу

  1. В YML нельзя использовать:

    • непечатаемые символы с ASCII-кодами от 0 до 31 (за исключением символов с кодами 9, 10, 13 — табуляция, перевод строки, возврат каретки);

    • эмодзи и другие специальные символы Юникода.

  2. Символы " & > < ' нужно заменять на эквивалентные коды:

    Символ в тексте

    Код для YML-файла

    		 
    "
&
>
<
'
    		 
    &quot;
&amp;
&gt;
&lt;
&apos;

    Символ в тексте

    Код для YML-файла

    		 
    "
&
>
<
'
    		 
    &quot;
&amp;
&gt;
&lt;
&apos;
    Примечание. Вы можете использовать символы "&><'в блоке CDATA в описании предложения.

  3. Допустимые кодировки YML-файла: UTF-8, windows-1251.

  4. В качестве разделителя целой и дробной частей любых чисел, указанных в качестве значений YML‑элементов, независимо от региональных установок используется только точка.

Пример YML‑файла

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2020-11-22T14:37:38+03:00">
    <shop>
        <name>BestSeller</name>
        <company>Tne Best inc.</company>
        <url>http://best.seller.ru</url>
        <currencies>
            <currency id="RUR" rate="1"/>
        </currencies>
        <categories>
            <category id="1">Бытовая техника</category>
            <category id="10" parentId="1">Мелкая техника для кухни</category>
        </categories>
        <delivery-options>
            <option cost="200" days="1"/>
        </delivery-options>
        <offers>
            <offer id="9012">
                <name>Мороженица Brand 3811</name>
                <url>http://best.seller.ru/product_page.asp?pid=12345</url>
                <price>8990</price>
                <currencyId>RUR</currencyId>
                <categoryId>10</categoryId>
                <delivery>true</delivery>
                <delivery-options>
                    <option cost="300" days="1" order-before="18"/>
                </delivery-options>
                <param name="Цвет">белый</param>
                <weight>3.6</weight>
                <dimensions>20.1/20.551/22.5</dimensions>
            </offer>
        </offers>
        <gifts>
            <!-- подарки не из прайс‑листа -->
        </gifts>
        <promos>
            <!-- промоакции -->
        </promos>
    </shop>
</yml_catalog>

Основные элементы YML

Элемент Описание
xml header

Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа.

yml_catalog

Любой XML-документ может содержать только один корневой элемент. Формат YML в качестве корневого использует элемент <yml_catalog> с атрибутом date.

Атрибут date

Дата и время момента, на который актуальны данные в файле.

Внимание. Убедитесь, что указываете в файле правильные дату и время. Не указывайте будущие дату и время — вместо них Маркет будет использовать дату и время загрузки файла. Неактуальное значение атрибута date приведет к проблемам в работе с предложениями.

Рекомендуется всегда заполнять атрибут date.. Если файл генерируется автоматически, желательно указывать дату и время начала генерации.

Допустимый формат значения основан на стандарте RFC 3339 (см. раздел 5.6) со следующими особенностями:

  • Между датой и временем должна стоять латинская буква T или пробел.

  • Можно не указывать секунды и часовой пояс. По умолчанию используется 0 секунд и часовой пояс домашнего региона магазина.

Примеры значений:

  • 2020-11-22T14:37:38+03:00 (рекомендуется).

  • 2020-11-22T14:37:38.

  • 2020-11-22 14:37.
shop

В элементе shop содержатся:

  • Элементы с информацией о магазине: названием, списком категорий, условиями доставки и т. п. Подробнее см. в разделе Элементы, входящие в shop.

  • Элемент offers со списком предложений магазина. В этот элемент нужно вставить по одному элементу offer для каждого предложения. Элемент offer может быть упрощенного типа (полное название товара — тип, производитель и модель — указывается в одном элементе) или произвольного типа (название товара составляется из трех разных элементов). Подробнее о различии типов см. в разделе Информация о товарах в форматах YML и CSV (offers, offer).

  • Элемент promos со списком акций магазина и элемент gifts со списком подарков (которые не размещаются на Маркете как отдельные товары) для акций «Подарок при покупке». В элемент promos нужно вставить по одному элементу promo для каждой акции, а в элемент gifts — по одному элементу gift для каждого подарка. Подробнее см. в разделе Промоакции (promos, gifts).
Элемент Описание
xml header

Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа.

yml_catalog

Любой XML-документ может содержать только один корневой элемент. Формат YML в качестве корневого использует элемент <yml_catalog> с атрибутом date.

Атрибут date

Дата и время момента, на который актуальны данные в файле.

Внимание. Убедитесь, что указываете в файле правильные дату и время. Не указывайте будущие дату и время — вместо них Маркет будет использовать дату и время загрузки файла. Неактуальное значение атрибута date приведет к проблемам в работе с предложениями.

Рекомендуется всегда заполнять атрибут date.. Если файл генерируется автоматически, желательно указывать дату и время начала генерации.

Допустимый формат значения основан на стандарте RFC 3339 (см. раздел 5.6) со следующими особенностями:

  • Между датой и временем должна стоять латинская буква T или пробел.

  • Можно не указывать секунды и часовой пояс. По умолчанию используется 0 секунд и часовой пояс домашнего региона магазина.

Примеры значений:

  • 2020-11-22T14:37:38+03:00 (рекомендуется).

  • 2020-11-22T14:37:38.

  • 2020-11-22 14:37.
shop

В элементе shop содержатся:

  • Элементы с информацией о магазине: названием, списком категорий, условиями доставки и т. п. Подробнее см. в разделе Элементы, входящие в shop.

  • Элемент offers со списком предложений магазина. В этот элемент нужно вставить по одному элементу offer для каждого предложения. Элемент offer может быть упрощенного типа (полное название товара — тип, производитель и модель — указывается в одном элементе) или произвольного типа (название товара составляется из трех разных элементов). Подробнее о различии типов см. в разделе Информация о товарах в форматах YML и CSV (offers, offer).

  • Элемент promos со списком акций магазина и элемент gifts со списком подарков (которые не размещаются на Маркете как отдельные товары) для акций «Подарок при покупке». В элемент promos нужно вставить по одному элементу promo для каждой акции, а в элемент gifts — по одному элементу gift для каждого подарка. Подробнее см. в разделе Промоакции (promos, gifts).

Текстовый формат

Текстовый формат с разделителями удобен при генерации прайс-листа из базы данных или редакторов электронных таблиц (например: Exсel, OpenOffice, Google Docs).

Требования к прайс-листу в текстовом формате

  1. Одна строка файла должна соответствовать одной строке электронной таблицы.

  2. В качестве разделителя полей используется запятая или точка с запятой (CSV) либо символ табуляции (TSV).

  3. Одна строка файла должна содержать описание одного предложения.

  4. Первая строка файла должна содержать названия полей.

  5. Кодировка файла должна быть UTF-8.

  6. Нельзя использовать табуляцию и перенос строки внутри полей.

  7. Файл не должен содержать пустых столбцов.

  8. Порядок столбцов (полей) не задан строго, но в пределах одного файла порядок столбцов (полей) должен быть одинаковым.

Примеры прайс-листов

Скачать пример с предложениями упрощенного типа

Скачать пример с предложениями произвольного типа

Примечание. Подробнее о различии типов см. в разделе Информация о товарах в форматах YML и CSV (offers, offer) и в описаниях: упрощенный тип, произвольный тип.