Catalog entity format overview¶

The catalog consists of structured product data, content, and translations. This section provides a detailed overview of these entities as well as how to work with market- and locale-specific information.

Related articles

• Guidance on working with catalog import files: catalog import overview
• Complete schemas and request requirements: import specification
• Contextualized, complete examples for common import scenarios: import examples
• Import strategies and scheduling: Scheduled imports

Product model¶

Items available for purchase are structured as product groups, which contain products, each with one or more variants.

Product group¶

The product group is the top level of the product model and represents the overall article. It contains attributes shared by all its products and variants.

{
    "key" : "1001",
    "productGroup" : {
      "suppressDuplicates": "false",
      "products" : {
        // As described in the product section
      }
    }
}

Each product group is identified by a unique key, which is referenced in any instruction that modifies the product group.

Related schemas: ProductGroup.

Product¶

A product represents a specific variation within a product group and includes attributes that distinguish it from other products in the same group. These are typically visible characteristics such as color, pattern, material, or visible size-related aspects like mattress thickness, which help customers easily differentiate products in listings or search results. A good rule of thumb is that products within a group typically have their own images.

Each product must contain at least one variant and should have at least one image.

{
  "1001-100": {
    "markets": ["uk"],
    "colorInitial": ["#FF0000"],
    "defaults": {
      // Product data
    },
    "overrides": {
      "*|sv-SE": {
        // Product data
      }
    },
    "images": {
      // As described in the images section
    },
    "variants": {
      // As described in the variant section
    }
  }
}

{
  "url": "/products/1001-100",
  "title": "Louisa black coat",
  "ontology": "Clothing > Outerwear > Coats",
  "category": ["c1", "c2"],
  "brand": "Luis Vitton",
  "sizeType": "Clothing",
  "description": "A fine coat for any occasion",
  "releaseDate": "2023-06-20T00:00:00+02:00",
  "rating": 5,
  "customLabels": {
    // As described in the custom attributes section
  },
  "customLengths": {
    // As described in the custom attributes section
  }
}

Related schemas: Product, ProductData.

Images¶

An image object defines a single image and may include multiple URLs representing different resolutions of the same image. These variations help optimize bandwidth usage and are especially useful for thumbnails. Each image must include at least one URL.

{
  "i1": {
    "typeInitial": "model",
    "defaults": {
      // Image data
    },
    "overrides": {
      "*|sv-SE": {
        // Image data
      }
    }
  }
}

{
  "urls": [
    {
      "url": "//cdn.example.com/products/p1?preset=200x200",
      "widthInitial": 200
    }, {
      "url": "//cdn.example.com/products/p1?preset=600x600",
      "widthInitial": 600
    }
  ],
  "caption": "The model is 176 cm tall and is wearing size S",
  "alt": "The model is 176 cm tall and is wearing size S",
  "tags": ["hero"],
  "customData": {
    "user": "u1",
    "type": "Instagram"
  }
}

Each image is identified by a unique key, which is referenced in the product's images map and in any instruction that modifies the image. Some attributes are provided directly on the image object, while most are defined in inner imageData objects that can be supplied as defaults and overrides.

Related schemas: Image, ImageData, UrlMeta.

Variant¶

A variant represents a stock-keeping unit (SKU) and includes attributes specific to that SKU. It typically reflects a difference in physical size, but can also represent variations like memory capacity or other product-specific features.

{
  "1001-100-1": {
    "defaults": {
      // Variant data
    }
  },
  "overrides": {
    "se|*": {
      // Variant data
    }
  }
}

Each variant is identified by a unique key, which is referenced in the product's variants map and in any instruction that modifies the variant. The variant attributes are defined in inner variantData objects that can be supplied as defaults and overrides.

{
  "url": "/products/1001-100-1?size=S",
  "stock": 12,
  "sellingPrice": 129.0,
  "listPrice": 199.0,
  "cost": 55.0,
  "size": ["S"],
  "storeStock": {
    "stockholm": 23
  },
  "customLabels": {
    // As described in the custom attributes section
  }
}

Sizes¶

A single physical size can be expressed in several formats. For example, a shirt can be considered both a size S and sizes 34 and 36 simultaneously. If multiple formats are known, all should be provided using sizeFormats instead of size. Multiple variants with the same format and value are allowed, as long as there is one format with a unique single value.

"sizeFormats": {
  "sml": ["S"],
  "eu": ["34", "36"]
}

Custom prices¶

Custom prices allow a single variant to have multiple prices. They are associated with price IDs, which must also be included when querying.

"customPrices": {
  "VIP": {
   "sellingPrice": 99.0,
   "listPrice": 199.0
  }
}

Store stock¶

The default stock level defines the online stock availability, while storeStock allows a variant to have store specific stock information. Store specific stock levels are associated with store IDs, which must also be included when querying.

"storeStock": {
  "stockholm": 23,
  "lund": 2
}

Related schemas: Variant, VariantData, Price.

Related articles: Custom prices feature, Store specific stock.

Content¶

Content enable visitors to find editorial content items on a site, such as FAQs, shipping, and contact information.

{
  "key": "842",
  "content": {
    "markets": ["se", "uk"],
    "type": "article",
    "defaults": {
      // Content data
    },
    "overrides": {
      "*|sv-SE": {
        // Content data
      },
      "se|*": {
        // Content data
      }
    },
    "image": {
      // As described in the images section
    }
  }
}

Each content item is identified by a unique key, which is referenced in any instruction that modifies the content. Some attributes are provided directly on the content object, while most are defined in inner contentData objects that can be supplied as defaults and overrides.

{
  "url": "uk/articles/its-finally-sweater-season-2020-11-20/",
  "title": "It's finally sweater season",
  "releaseDate" : "2023-08-20",
  "description": "Warm, comfortable, and stylish when it matters the most.",
  "customLabels": {
    "season": ["S1"]
  }
}

Related schemas: Content, ContentData, Image.

Translation¶

Translation 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. Translations apply to all Product, Variant and Content properties that match.

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 translation 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, age, gender, series, department, pattern, name, brand and custom label attributes, for example customLabels.season.

{
  "translation": {
    "locale": "en-GB",
    "attribute": "customLabels.season",
    "id": "AUT",
    "value": "Autumn"
  }
}

Related schemas: Translation.

Shared models¶

Custom attributes¶

Catalog items support several types of custom attributes. Each type offers specific features tailored to the kind of data it represents.

customLabels¶

Supports filters and facets, and works with translations. Useful for defining custom filtering or faceting options beyond standard attributes.

"customLabels": {
  "season": ["AUT"]
}

customLengths¶

Supports range queries and metric conversion. Can be used for secondary measurements, such as shipping size.

"customLengths": {
  "packageWidth": {
    "amount": 3.0,
    "unit": "dm"
  }
}

customNumbers¶

Supports numeric range queries. Useful for numeric attributes like the number of items in a package or other count-based values.

"customNumbers": {
  "pieces": 100.0
}

customJson¶

Supports raw JSON values. Useful for including flexible, presentational, or miscellaneous data that should be returned as-is in JSON responses.

"customJson": {
  "cardStyle": { "theme": "dark" }
}

customData¶

Handles non-facetable metadata. Used specifically for supplying additional data for image objects.

"customData": {
  "user": "u1",
  "type": "Instagram"
}

Refer to each item's schema to see which custom attribute types it supports.

Predefined measurements¶

Predefined measurements like width, height, length, depth, weight, and volume share product and variant values in facets, product selections and sorting. This means that there is a single facet for e.g. width that holds all width values regardless of whether they are provided at product or variant level.

In catalog imports, each product must have its predefined measurements specified, either at the product level or the variant level. If measurements are provided at the variant level, then all variants of the product must include values for the relevant measurements.

Each measurement consists of an amount and a unit, where valid units depends on the type of measurement.

Related schemas: Length, Weight, Volume.

Markets and locales¶

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.

{
  "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 URLs given specific circumstances. E.g. URLs 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:

1. Distinct overrides
2. Market overrides
3. Locale overrides
4. 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.

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.