Items

We consider an item anything that could be offered to an end-user, such as a product for sale, a news article, or a video.

Each item should have an identifier, which we expect to receive as a string, under the field ITEM_ID.

In addition to an identifier, we like to have additional metadata, such as the title, price, and any other attributes that could allow us to filter, categorise, and search items to your liking. To structurally manage this extra information we offer different metadata templates for each use case.

In this section we go over the schema of item metadata. To learn more about the packaging, delivery and usage of item metadata, please refer to the Managing item metadata how to page.

Item metadata templates

Before sending us your item metadata it is important that it is prepared correctly, so we can parse and ingest it without any issues. To simplify the preparation of your metadata we have a limited number of data templates that you can adhere to. Each template corresponds to a specific use case of the Froomle platform. While not all fields within a template are required, we highly encourage you to provide as many fields as possible within the chosen template, as it will improve your personalization performance.

Some fields in our templates are nested which doesn’t map directly to some of our accepted formats (e.g. CSV). For these formats we ask you to include these nested fields as their serialized JSON representation.

Base item metadata template

As our current 3 templates have a lot in common we created a base template which lists fields that are available in all the other templates.

Field Description

item_id*

string

Required. The unique identifier of the item.

environment*

string

Required. The environment to which the item belongs.

language*

string

Required. The metadata’s main language, if an item’s metadata is delivered in multiple languages specify the most dominant language here. The provided value should be a ISO 639-1 standard language code like en, fr, nl, en-us, nl-be, …​

item_type*

string

Required. Items is the collection of all different entities on your platform. Item type allows you to further specify which type of entity this item represents. E.g. article, video, profile, category, …​

title

string

Optional. The title of the item. If your item contains translations use the title_map field instead.

title_map

map<string, string>

Optional. A mapping of language_code → title. Use this field when your title has multiple translations. Keys in this map should be ISO 639-1 standard language codes like en, fr, nl, en-us, nl-be, …​

description

string

Optional. The description of the item. If your item contains translations use the description_map field instead.

description_map

map<string, string>

Optional. A mapping of language_code → description. Use this field when your description has multiple translations. Keys in this map should be ISO 639-1 standard language codes like en, fr, nl, en-us, nl-be, …​

uri

string

Optional. The uri of the item. If your item has a resource identifier unique to each language use the uri_map field instead.

uri_map

map<string, string>

Optional. A mapping of language_code → uri. Use this field when your item has resource identifiers unique to each language. Keys in this map should be ISO 639-1 standard language codes like en, fr, nl, en-us, nl-be, …​

tags

list<string>

Optional. Tags are often associated with items to provide extra context. While this field is optional it should be clear that tags carry valuable information for personalisation algorithms.

images

list<string>

Optional. If your item contains one or more images you can optionally provide their URLs using this field.

parent

string

Optional. When your items are structured in a hierarchy you can supply the parent identifier using this field.

ancestry_level

string

Optional. When your items are structured in a hierarchy you can specify the level of the provided item in the hierarchy. Valid values are (from highest to lowest in the hierarchy): group, item and model.

categories

list<list<string>>

Optional. As items often belong to a hierarchical category structure you can specify each path within the structure that can be used to reach the current item. Categories within a path should be listed from most general to most specific.

Specialized templates

For our most popular use cases we have created more specialized templates which extend the base template with extra information tailored to each use case. If your use case maps on one of these specialized templates you can leverage the extra level of detail they provide and improve your personalization experience even more.

  • Retail Template

  • News Template

  • Social Network Template

Inherits all the fields from the Base template (see above) +

Field Description

price*

double

Required. The retail/listing price of the item.

currency_code*

string

Required. ISO-4217 compliant triple-character currency code. E.g. EUR, USD, GBP, …​

costs

map<string, double>

Optional. Extra cost-related monetary amounts like: VAT, profit, purchase price, …​

stock_state

string

Optional. The current state of the product’s stock. Valid values are: IN_STOCK, OUT_OF_STOCK, PREORDER and BACKORDER.

available_stock

integer

Optional. Current number of articles in stock for this item.

original_price

double

Optional. The original price of a discounted product.

discount_percentage

double

Optional. The percentage of discount for discounted products. When both price and original_price are specified we can automatically compute this field if you don’t specify it. When you also provide this field along with the original_price and price fields, the provided discount percentage value will also be validated using both price values.

Inherits all the fields from the Base template (see above) +

Field Description

publication_datetime*

string

Required. ISO-8601 formatted timestamp string of the publication datetime of the news item.

end_datetime

string

Optional. ISO-8601 formatted timestamp string of the end of publication datetime of the news item.

access_type

string

Optional. When access to an article is restricted for certain users, use this field to specify the restriction. Valid values are: free, paid and subscribed.

Inherits all the fields from the Base template (see above) +

Field Description

publication_datetime*

string

Required. ISO-8601 formatted timestamp string of the publication datetime of the content item.

end_datetime

string

Optional. ISO-8601 formatted timestamp string of the end of publication datetime of the content item.

owner

string

Optional. User identifier of the owner of the content.

privacy

string

Optional. Privacy setting applied to the content piece which controls the visibility of the item. Valid values are: me, friends, friends_of_friends and public.

Item types

Item types can be used to distinguish items of substantially different kinds, such as news articles from videos, or physical products from services. However, smaller differences such as different kinds of household appliances do not typically warrant separate item types. Usually our customers have no more than a few item types at a time.

Fundamentally different kinds of items generally require different kinds of metadata. Therefore, each item type can have its own metadata structure.

If there is no such distinction between items in your system, then there will be just one item type, and you don’t have to worry about item types at all.

As we mentioned before, each item should have a string identifier. Such an identifier alone doesn’t fully identify an item, however. Items are fully identified by the pair (item_type, item_id). As such, two items of a different item type with the same item ID are considered unrelated.

We prefer you communicate these item types explicitly wherever possible. If you are unable to communicate item types to Froomle, contact your Solution Architect to discuss if they can be determined from context.

A note about timestamps

It can be useful to include timestamps as part of the item metadata. Commonly, time restrictions on the recommendability of an item apply. For instance, we may not be allowed to recommend news articles that are too old, or a soon to be released product may not be allowed to be shown before a certain time.

When sharing timestamps between different systems – such as between yours and ours – the time offset is often a cause for confusion. A timestamp without this information (either by context or explicitly given) does not uniquely define a point in time.

If you provide us with timestamps, please either:

  • Provide a time offset with it, such that it is a fully qualified timestamp. With the ISO-8601 notation, the preferable format is:

    yyyy-mm-ddThh:mm:ss+|-hh:mm

    For example:

    2019-09-06T12:00:00+02:00

    This way no assumptions need to be made.

  • Provide us timestamps in UTC+00. For any timestamp without any time zone or offset information, we assume UTC+00.