Internet Offer Format (IOF) for Shops ver. 3.0

Technical Specification
Language used in this document: English (en-US)

Introduction

IOF for Shops ver. 3.0 is the product offer description format, based on XML. This format is fully portable and easy to implement in any IT system.

The IOF for Shops was developed for the IAI Downloader application.

Although, it is possible to use this format in panel IdoSell Shop in the section PRODUCTS/ Product import, update and restore or in other system dedicated for processing data of products.

This document concerns the entire structure of files included in the IOF for Shops ver. 3.0 format and a client-oriented implementation procedure.

Attachments to this document:
example XML files,
example XSD files (XML Schema).

Terms and Conditions of using IOF (Internet Offer Format) for Shops))

Please note that any version of the IOF (Internet Offer Format) for Shops is a product of the IAI S.A. and is distributed on the terms of Creative Commons license defined by Creative Commons Attribution-NoDerivative Works 2.5, including the following:

  1. You are allowed to copy, distribute and to use the IOF format in terms defined hereby by the IAI S.A. and this document.
  2. You may not alter, transform or use it in any modified form for any other purposes.

It should be stressed that the use of the IOF version 2.0 is unadvisable, because it is considered obsolete. We strongly recommend using IOF version 2.6 or later.

Idea of IOF for Shops format

The IOF for Shops format uses meta-data to describe products for the IAI Downloader. It is not essential to use exactly that program. This format is ultra portable and can be used in any applications processing full data of products - for the needs of e-commerce. The IOF for Shops format describes products in integration process between supplier and seller (distributor), who wishes for the widest assortment and the best conditions of sale (Schematics no. 1).

Schematics no. 1, The IOF principle of operation.

The IOF for Shops has modular structure referring to particular categories of information. Reference mechanism is performed via URL requests to files of the IOF for Shops format. An integral part of this document is the gateway.xml file, which is a so-called gateway. That file is a main part of the IOF for Shops format.

This file holds following elements:

  • Meta-data describing a supplier,
  • Information about time period within offer is valid,
  • URL to file containing a full description of offer (full.xml),
  • URL to file containing a products that have been changed in the last 30 minutes (full_change.xml),
  • URL to file containing a short description of offer (light.xml),
  • URL to file containing a list of categories (categories.xml),
  • URL to file containing a list of sizes (sizes.xml),
  • URL to file containing a list of producers (producers.xml),
  • URL to file containing a list of measure units (units.xml),
  • URL to file containing a list of parameters (parameters.xml),
  • URL to file containing a list of product series (series.xml),
  • URL to file containing a list of warranties (warranties.xml),
  • URL to file containing a list of stocks (stocks.xml),
  • URL to file containing configuration of offer import (preset.xml).

Schematics no. 2 shows a structure of the IOF for Shops files:

Explanation to Schematics no. 2:

  • the main file of the format is the gateway.xml. It contains information on supplier and links to the rest of offer files,
  • the first file of the format is the full.xml. It contains basic information of products – descriptions and titles multi-language, photos, attributes,
  • second file is the light.xml. It contains information on stock quantities, producer codes, weights and prices,
  • stocks.xml, sizes.xml, series.xml, warranties.xml, categories.xml, units.xml, producers.xml, parameters.xml are additional files, strictly associated with main files – they contain information on attributes multi-language of products in offer,
  • preset.xml is file that contains configuration of offer import for the use by applications handling IOF for Shops offers.

All these elements are especially useful for those, who do not use the IAI Downloader. Why? Because it becomes easier to import and export product descriptions when you make use of the IOF for Shops
format. So:

  • If you are a seller (offer receiver) prepare appropriate tools designed for processing XML files. If you do not have time to work with these files, you can use the IAI Downloader which is entirely integrated with the IdoSell.com system platform.

  • If you are a supplier (wholesaler), and you wish to integrate your wholesale store with retail stores, prepare an appropriate IOF for Shop format files in accordance with this specification. Familiarize yourself with structure and requirements of each file linked directly in the gateway.xml.

In order to prepare particular XML files, familiarize yourself with contents of this document.

What has changed since 2.6

IOF for Shops version 3.0 released

IOF for Shops ver. 3.0 is currently available. We have extended functionality of this format, by adding new features listed below. This document concerns only the IOF for Shops ver. 3.0.

List of modifications made in 3.0 version

  1. in the gateway.xml file:
    • we have added an optional @generated_by attribute in the node <provider_description> that allows you to return information about the platform from which the offer was generated,
    • we have added in the node <provider_description><meta><address> an additional node <province> that allows you to return information about the province, district, region, province or state for the given address,
    • in the node <provider_description><meta><time><offer> we have changed the names of the attributes @date_created and @date_expires to @created and @expires,
    • we have added all offer files for nodes except for the light node, the @hash attribute that returns the md5 key of the given file and the optional @changed attribute that returns the date and time of the last modification of the file,
    • in the <full> node we have added an optional node <changes> containing any number of <change> nodes returning URLs to differential files containing information about the goods and their nodes that have changed in the last 30 minutes.
  2. in the full.xml file:
    • in the <offer> node an optional @generated_by attribute has been added that allows you to return information about the platform from which the offer was generated and the attribute,
    • in the <offer> / <products> / <product> node, the @type attribute was added, returning information about the type of product offered (regular, packaging, virtual, bundle, collection, service) and the @removed attribute informing that the given product ceased to be already offered and will not be returned any more,
    • node name iaiext: category_iai has been changed to category_idosell, and the node itself has become the primary offer node returned without the prefix iaiext:,
    • the url_mobile attribute has been added to the <card> node, which until now was supported by the extension IOF Extensions,
    • in the <product> node:
      • next to the already existing node <strikethrough_retail_price> returning information about the basic strikethrough retail price, a <strikethrough_wholesale_price> node has been added which returns information about the basic strikethrough wholesale price,
      • node <bundle_group> has been added returning nodes <bundle_product> containing information about products of sets and collections, how they are presented in size and the quantity offered.
    • in the node <product><sizes><size>:
      • the value generation for the @text_id attribute has been corrected, which should return the name of the offered size,
      • next to the existing <strikethrough_retail_price> node that returns information about the strikethrough retail price for a given size, a <strikethrough_wholesale_price> node has been added that returns information about the strikethrough wholesale price for a given size,
      • the @iaiext attributes: location_id and @iaiext: location_text_id so far supported by the extension IOF Extensions have become the basic attributes of the <stock> node returned without the prefix iaiext:,
    • the name of the @date_changed attribute returned in at all nodes in the <product> <images> node has been changed to @changed,
    • so far supported by the extension IOF Extensions, the attributes @iaiext: distinction, @iaiext: group_distinction, @iaiext: hide, @iaiext: auction_template_hide, @iaiext: context_id have become the basic attributes of the <parameter> and <value> nodes returned without the prefix iaiext:,
    • in the <group> node that has been so far supported by the extension IOF Extensions, the @iaiext attribute: first_product_id has become the primary node attribute returned by the prefix iaiext:,
    • in the node <attachments><file>:
      • a new @version attribute has been added, returning information about the version of the given attachment (demo or full),
      • attributes @iaiext: enable, @iaiext: attachment_file_type, @iaiext: download_log, @iaiext: attachment_file_extension supported so far by the extension IOF Extensions, have become the basic attributes of the node returned without the prefix iaiext:.
  3. in the light.xml file:
    • the name of the strikethrough_price node has been changed to strikethrough_retail_price to be consistent with the name of this node in the full.xml file,
    • we have added a new node <strikethrough_wholesale_price>, which in the <product> node is responsible for returning information about the base strikethrough wholesale price, and in the <sizes> <size> node for returning information about the strikethrough wholesale price of a given size,
  4. the offer has been extended by the possibility of generating additional optional full_change.xml files responsible for returning information about products that have changed in the last 30 minutes.

Descriptive conventions and common issues

There are many common issues that apply to all files of the IOF for Shops format. In order not to duplicate them, we introduce them in this section. It concerns tags and attributes in all XML files included in the IOF for Shops format.

To simplify the XML code, we have created following descriptive conventions for tags and attributes for the IOF for Shops XML and XSD files:

  • size@id - specifies size tag and its attribute id,
  • @name - specifies attribute name for current tag,
  • <product> - specifies product tag.

Attributes such as @code, @code_producer may contain following symbols: '0-9', 'a-z', 'A-Z', '_', '-'. Content of attributes above must be unique for each product, size, etc. It is not allowed to enter the same data to @id, @code and @code_producer tags

Every file must contain attributes of version and format (placed inside the main tag). For version 3.0 - @file_format="IOF" and @version="3.0". In every of the IOF for Shops format files, except gateway.xml, there is an information about current language of particular file, e.g. eng – it is held in the main tag in @language attribute. This attribute is required.

An xml:lang attribute defines language of particular element. Check ISO 639.2 codes for the representation of names of languages.

Elements supported by multi-language feature:

  • name of product,
  • short description of product,
  • long description of product,
  • name of category,
  • name of size,
  • name of unit of measure,
  • name, description and graphics of parameters,
  • name of series,
  • name and description of warranty,
  • name of attachment,
  • name of stock.

Files such as: categories.xml, units.xml, series.xml, parameters.xml, warranties.xml,sizes.xml may contain @name (file warranties.xml may include also @description) in many languages (thanks to xml:lang attribute) and those contents will be imported to the IdoSell Shop by means of the IAI Downloader. These elements may be defined by only one language in the full.xml file - content in this language will be assigned to product.

Notice:

xml:lang attribute is optional in every element that supports multi-language feature.

The multi-language feature applies to: name of product, name of version product, name of group versionproduct, its short and long description. The full.xml file may include those contents in many languages. All defined contents will be imported.

Every customer, to whom the IOF for Shops document is directed, is called a business or target customer.

Documentation files with sample XML files and XSD validators