Catalog overview¶

The catalog format describes how data needs to be formatted and structured to be imported into Voyado Elevate. This section provides an overview of the catalog format and catalog imports. For complete schemas and request details, see the catalog import specification.

The catalog consists of the entities productGroup, content and translation.
Catalog imports must be encoded using UTF-8.
Catalog imports must be sent with Content-Type: application/jsonlines.
Catalog imports must consist of json lines with a single Operation on each line, describing a change of the catalog.
All referenced markets and locales must be configured prior to importing catalog data.

JSON Lines¶

JSON Lines (JSONL) is a format for storing JSON data where each line of the file contains a valid JSON object. These JSON objects are separated by newline characters, and each line can be treated as an independent JSON entity.

Catalog imports consists of one or more Operation objects, provided as separate JSON lines.

Import types¶

Two types of catalog imports are supported, one to replace all catalog data and one to update the catalog data. The request method and the requirements of the operations differ between these imports. If any import fails, the catalog data remains unchanged.

Replace catalog¶

HTTP method: PUT
Replacing the catalog data, fully deletes all previously loaded data and replaces it with the data in the import. Operations within these imports must only contain replace instructions.

Example¶

application/jsonlines

{"replace": {"key": "pg1", "productGroup": {"products": {"p1": {"markets": ["uk"], "defaults": {"url": "/uk/products/p1", "title": "Louisa black coat"}, "variants": {"p1-v1": {"defaults": {"stock": 2, "sellingPrice": 129.0, "listPrice": 199.0, "cost": 55.0}}}}}}}}
{"replace": {"key": "c1", "content": {"markets": ["uk"], "type": "link", "defaults": {"title": "Shipping and Delivery", "url": "/us/customer-service/shipping-and-delivery"}}}}

Update catalog¶

HTTP method: POST
Updates to the catalog data can be made in various ways by using different instructions. When updating the catalog, any of the available instructions can be used within an Operation.

Each operation is executed in the provided order, e.g. replace before remove of an object will result in a different state than remove before replace.

Example¶

application/jsonlines

{"remove": {"productGroup": "pg37"}}
{"remove": {"content": "c22"}}
{"replace": {"key": "pg1", "productGroup": {"products": {"p1": {"markets": ["uk"], "defaults": {"url": "/uk/products/p1", "title": "Louisa black coat"}, "variants": {"p1-v1": {"defaults": {"stock": 2, "sellingPrice": 129.0, "listPrice": 199.0, "cost": 55.0}}}}}}}}
{"edit": {"key": "c1", "content": {"defaults": {"title": "Returns"}}}}

Format overview¶

Each Operation in the import must always contain a single instruction.

The format of each instruction varies, for example all types of removal instructions have a very basic structure, simply specifying the context of what to remove.

Instructions that can add or modify data such as replace and edit contain complete entities or parts of the entities productGroup, content and translation.

editAttributes is a unique instruction for modifying inner objects, without the need to specify keys of the entire product data hierarchy. This instruction operates on the entities product and variant and is typically used for stock and price updates.

Market and locale availability¶

Market availability for content and products are specified in the attribute markets. All variants that belong to a product will automatically become available on all the markets that the product is available on. A productGroup will be available for markets where at least one of its products is available, and will only include the products available for that market.

All product data and content will be available on all locales that are supported by a market according to the configuration, unless explicitly limited. Note, only content and imagery supports explicit locale limitations.

Example¶

Given the product group example below, requests to the following markets would yield the following results:

Market uk: Product group pg1, containing products p1 and p2
Market se: Product group pg1, containing product p2
Market us: No product groups

The variants p1-v1 and p1-v2 will always be returned when p1 is returned, and p2-v1 when p2 is returned.

Product group example

{
  "key": "pg1",
  "productGroup": {
    "products": {
      "p1": {
        "markets": ["uk"],
        "...": "omitted for brevity",
        "variants": {
          "p1-v1": {
            "...": "omitted for brevity"
          },
          "p1-v2": {
            "...": "omitted for brevity"
          }
        }
      },
      "p2": {
        "markets": ["uk", "se"],
        "...": "omitted for brevity",
        "variants": {
          "p2-v1": {
            "...": "omitted for brevity"
          }
        }
      }
    }
  }
}

Defaults and overrides¶

When making a request to Voyado Elevate, a market and locale is always supplied. The entities which can be returned are determined by the market and locale availability but the data that the entities contain are determined by how the data is supplied within each entity.

Structural information such as included imagery and variants, as well as a selected few properties, such as content type and product colors are provided on the entities themselves. This means that the information cannot differ for different market and locale request context. But the majority of properties can vary with the request context. These attributes are located within entity specific Data objects called defaults, and can be overridden using overrides. Entities that support defaults and overrides include content, product, variant and image.

Properties provided within defaults are returned for all request contexts with the correspondingly provided default value, unless overridden. In such cases, the overridden value of the property is returned.

Overrides are provided as a map of data keys to the properties to override, where the data key determines when to apply the override. Overrides are only relevant for retailers that have or plans on supporting multiple markets or locales.

Data keys¶

Data keys consist of a market identifier and a locale, separated by a pipe [market]|[locale]. The asterisk * is a special identifier that signifies it is applicable for all markets or locales, e.g. [market]|* or *|[locale].

Locale overrides¶

Locale overrides refer to overrides that apply for a specific locale, regardless of market. Data keys for such overrides are constructed using * instead of a specific market, followed by the locale. A good rule of thumb is that locale overrides should be used for all localized text information that isn't intended for, or supported in, filters and product selections. Good examples include title and description.

Data key example: *|en-GB.

Market overrides¶

Market overrides refer to overrides that apply for a specific market, regardless of locale. Data keys for such overrides are constructed by the market identifier, followed by using * instead of a specific locale. Market overrides should be used to override properties that will be used in filters and product selections as well as any attribute that is connected to the market rather than the locale.

Some properties can only be overridden using market overrides, this is true for attributes which requires locale consistency, such as rating, releaseDate and stock. Properties used in filters and product selections with localized values should be localized using translations.

Data key example: uk|*.

Distinct overrides¶

Distinct overrides refer to overrides that apply for a specific locale in a specific market. Data keys for such overrides are constructed by the market identifier, followed by the specific locale.

Distinct overrides should not be used at all in the majority of integrations. When used, it is for very specific circumstances or use-cases. If distinct overrides are used a lot, the catalog feed is likely modeled incorrectly. One use case where distinct overrides are reasonable to use, are for url:s given specific circumstances. E.g. url:s that include both market and locale, and no post-processing of them are made on the site.

Data key example: uk|en-GB.

Value evaluation order¶

Values of properties are resolved according to the following priority:

Distinct overrides
Market overrides
Locale overrides
defaults

Meaning that if a property is included in both a distinct, market and locale override, the value in the distinct override will be the resulting value for requests with that market and locale combination. However, overridden values should under normal circumstances only be provided as a single type of override.

Data locale¶

For each entity specific Data object, e.g. defaults and each override, an optional attribute called dataLocale can be provided. This attribute informs Voyado Elevate of the locale of the actual content. For overrides containing locales, the content is assumed to match the locale of the override unless otherwise specified.

dataLocale is recommended to be provided for defaults when possible.

Translations¶

Translations is a separate entity that can be imported within a catalog feed. A translation is a mapping of an id for a specific property, to a localised value.

Using id:s in filters and product selections with translations as a mean to localise the presentational information, ensures stable filters and product selections. This means that localised presentational values can be altered via translations, without changing filter definitions or product selections. Translations also enables stable cross market and locale filters and product selection, meaning the same id can be used in multiple markets while still having differently localised presentational values.

If a property supporting translations lack a translation for a locale, the id itself will be used as the presentational value. Translation support is currently limited to the attribute category, series and custom label attributes, for example customLabels.season.

Example¶

application/jsonlines

{"replace": {"translation": {"locale": "en-GB", "attribute": "category", "id": "c1", "value": "Pants > Jeans"}}}
{"replace": {"translation": {"locale": "sv-SE", "attribute": "customLabels.season", "id": "AUT", "value": "Höst"}}}
{"replace": {"translation": {"locale": "en-GB", "attribute": "customLabels.season", "id": "AUT", "value": "Autumn"}}}

Guidelines¶

Aim for the highest level of abstraction when modeling defaults and overrides
For all properties that are shared across markets and locales for an entity, use defaults
When using overrides, place data where it naturally belongs when possible
Distinct overrides should only be used in very rare cases
Localize values using translations for all properties that are used as filters and product selections
Follow best practices

Specific use cases¶

Defaults as fallback¶

An optional usage of defaults is to use it as fallback data. This can be applicable when all properties are well-defined for the entities in a certain market and locale and are acceptable to use for other market and locale combinations as well, when no other data is present.

Unique locales per market¶

When having exactly one locale per market and no locales are ever re-used, all overrides can be supplied for each market and locale combination using market overrides. If locales are started being reused across markets, it is however strongly recommended to generalize the locale information to locale overrides at that point.

Note that distinct overrides are not recommended for this use case.