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.