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:

Filename	Description
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

JSONPath	Details
$.meta.attributes	Collection of meta attributes.
$.meta.attributes[].attribute_id	Attribute identifier. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.meta.attributes[].type	Attribute type.
$.meta.attributes[].names	Collection of attributes names.
$.meta.attributes[].names[].locale	Specified locale for the attribute name (i18n localisation, e.g. en_GB or fr_FR).
$.meta.attributes[].names[].name	Localised attribute name.
$.meta.attributes[?(@.attribute_id=='categories')].values	Collection of all category trees.
$.meta.attributes[?(@.attribute_id=='categories')].values[].category_id	Unique 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[].names	Collection of category names in different locales.
$.meta.attributes[?(@.attribute_id=='categories')].values[].names[].locale	Locale for category name (i18n localisation, e.g. en_GB or fr_FR).
$.meta.attributes[?(@.attribute_id=='categories')].values[].names[].value	Category name in this particular locale.
$.meta.attributes[?(@.attribute_id=='categories')].values[].children	Collection of child categories with the same structure.
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].category_id	Child 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[].names	Collection of Child category names in different locales.
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].names[].locale	Specifies locale for the Child category name (i18n localisation, e.g. en_GB or fr_FR).
$.meta.attributes[?(@.attribute_id=='categories')].values[].children[].names[].value	Localised 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 _)

JSON Path	Details
$.products	Collection of all products.
$.products[].product_id	Identifier of the product. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.products[].locales	Collection of locales (i18n localisation, e.g. en_GB or fr_FR).
$.products[].attributes	Collection of product attributes.
$.products[].attributes[].attribute_id	Attribute 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[].values	List of attributes values.
$.products[].attributes[].values[].locale	Language/country combination for which the value applies (i18n localisation, e.g. en_GB or fr_FR).
$.products[].attributes[].values[].value_id	Unique 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[].value	Value 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"
        }
    ]
}

You do not have to supply a locale value for attributes with non-localisable base-types int, float and text.

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 _)

JSONPath	Details
$.variants	Collection of all variants.
$.variants[].variant_id	Identifier of the variant. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
$.variants[].product_id	Identifier 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[].locales	Collection of locales (i18n localisation, e.g. en_GB or fr_FR).
$.variants[].attributes	Collection of variant attributes.
$.variants[].attributes[].attribute_id	Attribute 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[].values	List of attributes values.
$.variants[].attributes[].values[].locale	Language/country combination for which the value applies (i18n localisation, e.g. en_GB or fr_FR).
$.variants[].attributes[].values[].value_id	Unique 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[].value	Value 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"
        }
    ]
}

You do not have to supply a locale value for attributes with non-localisable base-types int, float and text.