Full Feed JSON Data Format
This page describes the data format to follow when implementing a JSON integration with Fredhopper.
Overview
Fredhopper uses 3 JSON files to model your item data and import this into FAS. These are:
meta.json
Defines the hierarchical category structure for the product catalogue and lists all of the attributes that are used, including their base-type.
products-n.json
Defines products and associates them with categories.Defines products, associates them with categories and lists the actual values for each product / attribute combination.
variants-n.json
Defines variants, associates them with a product and lists the actual values for each variant / attribute combination (optional).
If your data model is such that there is no concept of variants, then the variants JSON file(s) can be omitted.
The products and variants JSON files should only ever contain a maximum of 10,000 items within them in order to be processed successfully in a timely manner.
Additional files should be added and the item data should be split out when there are more than 10,000 products and/or 10,000 variants, e.g. products-0.json, products-1.json, products-2.json, variants-0.json, variants-1.json, variants-2.json etc.
meta.json
The meta.json file must adhere to the following guidelines:
All categories and the meta data for the attributes must be provided in a file named meta.json
UTF-8 encoded
Only printable characters, i.e. no control characters
All category_id values must start with a lowercase letter
The category_id values can only contain lowercase alphanumeric characters (a-z and 0-9)
The category_id values must never contain hyphens '-' or underscores '_'
The attribute_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)
The best practice is to set the top-level category_id value as 'catalog01'
The top-level category is always a single category
$.meta.attributesCollection of meta attributes.
$.meta.attributes[].attribute_idAttribute identifier. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.meta.attributes[].typeAttribute type.
$.meta.attributes[].namesCollection of attributes names.
$.meta.attributes[].names[].localeSpecified locale for the attribute name (i18n localisation, e.g. en_GB or fr_FR).
$.meta.attributes[].names[].nameLocalised attribute name.
$.meta.attributes[?(@.attribute_id=='categories')].valuesCollection of all category trees.
$.meta.attributes[?(@.attribute_id=='categories')].values[].category_idUnique identifier of the category. A category_id should only ever contain lowercase alphanumeric characters only and should not contain underscores '_'. Whitespace, hypens, quotation marks, etc. are not allowed.
$.meta.attributes[?(@.attribute_id=='categories')].values[].namesCollection of category names in different locales.
$.meta.attributes[?(@.attribute_id=='categories')].values[].names[].localeLocale for category name (i18n localisation, e.g. en_GB or fr_FR).
$.meta.attributes[?(@.attribute_id=='categories')].values[].names[].valueCategory name in this particular locale.
$.meta.attributes[?(@.attribute_id=='categories')].values[].childrenCollection of child categories with the same structure.
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].category_idChild category ID value. A category_id should only ever contain lowercase alphanumeric characters only and should not contain underscores '_'. Whitespace, hypens, quotation marks, etc. are not allowed.
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].namesCollection of Child category names in different locales.
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].names[].localeSpecifies locale for the Child category name (i18n localisation, e.g. en_GB or fr_FR).
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].names[].valueLocalised Child category name value.
Example
A single universe (catalog01) called 'Store' with one locale (en_GB)
{
"meta": {
"attributes": [
{
"attribute_id": "categories",
"type": "hierarchical",
"values": [
{
"category_id": "catalog01",
"children": [
{
"category_id": "women",
"children": [
{
"category_id": "shoes",
"names": [
{
"locale": "en_GB",
"name": "Shoes"
}
]
}
],
"names": [
{
"locale": "en_GB",
"name": "Women"
}
]
},
{
"category_id": "electricals",
"children": [],
"names": [
{
"locale": "en_GB",
"name": "Electricals"
}
]
}
],
"names": [
{
"locale": "en_GB",
"name": "Store"
}
]
}
]
},
{
"attribute_id": "_imageurl",
"names": [
{
"locale": "en_GB",
"name": "Image URL"
}
],
"type": "asset"
},
{
"attribute_id": "_thumburl",
"names": [
{
"locale": "en_GB",
"name": "Thumb URL"
}
],
"type": "asset"
},
{
"attribute_id": "name",
"names": [
{
"locale": "en_GB",
"name": "Name"
}
],
"type": "text"
},
{
"attribute_id": "colour",
"names": [
{
"locale": "en_GB",
"name": "Colour"
}
],
"type": "set"
}
]
}
}products-n.json
Each products-n.json file must adhere to the following guidelines:
All products and their attributes must be provided in a file name products-0.json
A maximum of 10,000 product items should exist in each JSON file, with the file names increasing incrementally in ascending order where necessary, i.e. products-0.json, products-1.json, products-2.json etc.
UTF-8 encoded
Only printable characters (i.e. no control characters)
Line breaks and other formatting can be used within the attribute value fields only, e.g. the html tag <br> can be used to add a line break to descriptive text
The product_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)
The value_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)
$.productsCollection of all products.
$.products[].product_idIdentifier of the product. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.products[].localesCollection of locales (i18n localisation, e.g. en_GB or fr_FR).
$.products[].attributesCollection of product attributes.
$.products[].attributes[].attribute_idAttribute identifier from the meta.json file. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.products[].attributes[].valuesList of attributes values.
$.products[].attributes[].values[].localeLanguage/country combination for which the value applies (i18n localisation, e.g. en_GB or fr_FR).
$.products[].attributes[].values[].value_idUnique identifier of the attribute value (this is only required for list and set attribute types). A unique value_id must be assigned to each unique value that exists for the attribute across the catalogue. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.products[].attributes[].values[].valueValue of product attribute.
Example
Two products in one locale (en_GB) each with three attributes
{
"products": [
{
"attributes": [
{
"attribute_id": "categories",
"values": [
{
"value": "shoes"
}
]
},
{
"attribute_id": "name",
"values": [
{
"locale": "en_GB",
"value": "Red Shoes"
}
]
},
{
"attribute_id": "_imageurl",
"values": [
{
"locale": "en_GB",
"value": "https://www.google.com/imgres?imgurl=https%3A%2F%2Fpreviews.123rf.com%2Fimages%2Fbaiajaku%2Fbaiajaku1704%2Fbaiajaku170400004%2F75391840-sexy-red-shoes-high-heels-are-on-white-background-.jpg&imgrefurl=https%3A%2F%2Fwww.123rf.com%2Fphoto_75391840_sexy-red-shoes-high-heels-are-on-white-background-.html&docid=OKAdSxFixkXzzM&tbnid=9wVZ0j8DuIgoXM%3A&vet=10ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc..i&w=1300&h=866&bih=1307&biw=2560&q=red%20shoes&ved=0ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc&iact=mrc&uact=8"
}
]
},
{
"attribute_id": "_thumburl",
"values": [
{
"locale": "en_GB",
"value": "https://www.google.com/imgres?imgurl=https%3A%2F%2Fpreviews.123rf.com%2Fimages%2Fbaiajaku%2Fbaiajaku1704%2Fbaiajaku170400004%2F75391840-sexy-red-shoes-high-heels-are-on-white-background-.jpg&imgrefurl=https%3A%2F%2Fwww.123rf.com%2Fphoto_75391840_sexy-red-shoes-high-heels-are-on-white-background-.html&docid=OKAdSxFixkXzzM&tbnid=9wVZ0j8DuIgoXM%3A&vet=10ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc..i&w=1300&h=866&bih=1307&biw=2560&q=red%20shoes&ved=0ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc&iact=mrc&uact=8"
}
]
}
],
"locales": [
"en_GB"
],
"product_id": "p100001"
},
{
"attributes": [
{
"attribute_id": "categories",
"values": [
{
"value": "electricals"
}
]
},
{
"attribute_id": "name",
"values": [
{
"locale": "en_GB",
"value": "Philips DAB Radio"
}
]
},
{
"attribute_id": "_imageurl",
"values": [
{
"locale": "en_GB",
"value": "https://www.google.com/aclk?sa=L&ai=DChcSEwjXr7erhvTlAhWJre0KHcyWBnwYABAMGgJkZw&sig=AOD64_3MBHXZueSfoJ5QCUbvLTCrRGZsvg&ctype=5&q=&ved=0ahUKEwiPsLCrhvTlAhWloXEKHRu-BhEQvhcIag&adurl="
}
]
},
{
"attribute_id": "_thumburl",
"values": [
{
"locale": "en_GB",
"value": "https://www.google.com/aclk?sa=L&ai=DChcSEwjXr7erhvTlAhWJre0KHcyWBnwYABAMGgJkZw&sig=AOD64_3MBHXZueSfoJ5QCUbvLTCrRGZsvg&ctype=5&q=&ved=0ahUKEwiPsLCrhvTlAhWloXEKHRu-BhEQvhcIag&adurl="
}
]
}
],
"locales": [
"en_GB"
],
"product_id": "p100002"
}
]
}variants-n.json
Each variants-n.json file must adhere to the following guidelines:
All variants and their attributes must be provided in a file name variants-0.json
A maximum of 10,000 variant items should exist in each JSON file, with the file names increasing incrementally in ascending order where necessary, i.e. variants-0.json, variants-1.json, variants-2.json etc.
UTF-8 encoded
Only printable characters (i.e. no control characters)
Line breaks and other formatting can be used within the attribute value fields only, e.g. the html tag <br> can be used to add a line break to descriptive text
The variant_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)
The value_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)
$.variantsCollection of all variants.
$.variants[].variant_idIdentifier of the variant. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.variants[].product_idIdentifier of the product to which this variant is related. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.variants[].localesCollection of locales (i18n localisation, e.g. en_GB or fr_FR).
$.variants[].attributesCollection of variant attributes.
$.variants[].attributes[].attribute_idAttribute identifier from the meta.json file. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.variants[].attributes[].valuesList of attributes values.
$.variants[].attributes[].values[].localeLanguage/country combination for which the value applies (i18n localisation, e.g. en_GB or fr_FR).
$.variants[].attributes[].values[].value_idUnique identifier of the attribute value (this is only required for list and set attribute types). A unique value_id must be assigned to each unique value that exists for the attribute across the catalogue. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.variants[].attributes[].values[].valueValue of variant attribute.
Example
Two products that each have two variants which are based on different colour options
{
"variants": [
{
"attributes": [
{
"attribute_id": "colour",
"values": [
{
"locale": "en_GB",
"value_id": "blue",
"value": "Blue"
}
]
}
],
"locales": [
"en_GB"
],
"product_id": "p100001",
"variant_id": "v100001_blue"
},
{
"attributes": [
{
"attribute_id": "colour",
"values": [
{
"locale": "en_GB",
"value_id": "red",
"value": "Red"
}
]
}
],
"locales": [
"en_GB"
],
"product_id": "p100001",
"variant_id": "v100001_red"
},
{
"attributes": [
{
"attribute_id": "colour",
"values": [
{
"locale": "en_GB",
"value_id": "black",
"value": "Black"
}
]
}
],
"locales": [
"en_GB"
],
"product_id": "p100002",
"variant_id": "v100002_black"
},
{
"attributes": [
{
"attribute_id": "colour",
"values": [
{
"locale": "en_GB",
"value_id": "silver",
"value": "Silver"
}
]
}
],
"locales": [
"en_GB"
],
"product_id": "p100002",
"variant_id": "v100002_silver"
}
]
}Last updated