> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/sending-and-managing-product-data/flatfiles/fullprodfeed/full-feed-json-data-format.md).

# 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:

<table><thead><tr><th width="289">Filename</th><th>Description</th></tr></thead><tbody><tr><td>meta.json</td><td>Defines the hierarchical category structure for the product catalogue and lists all of the attributes that are used, including their base-type.</td></tr><tr><td>products-<em>n</em>.json</td><td>Defines products and associates them with categories.Defines products, associates them with categories and lists the actual values for each product / attribute combination.</td></tr><tr><td>variants-<em>n</em>.json</td><td>Defines variants, associates them with a product and lists the actual values for each variant / attribute combination (optional).</td></tr></tbody></table>

{% hint style="warning" %}
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.
{% endhint %}

### meta.json <a href="#dataintegrationspecification-csvproductdata-categories.csv" id="dataintegrationspecification-csvproductdata-categories.csv"></a>

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

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

#### **Example**

A single universe (catalog01) called 'Store' with one locale (en\_GB)

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```json
{
    "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"
            }
        ]
    }
}
```

{% endcode %}

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

<table data-full-width="true"><thead><tr><th width="457">JSON Path</th><th>Details</th></tr></thead><tbody><tr><td><pre><code>$.products
</code></pre></td><td>Collection of all products.</td></tr><tr><td><pre><code>$.products[].product_id
</code></pre></td><td>Identifier of the product. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.</td></tr><tr><td><pre><code>$.products[].locales
</code></pre></td><td>Collection of locales (i18n localisation, e.g. en_GB or fr_FR).</td></tr><tr><td><pre><code>$.products[].attributes
</code></pre></td><td>Collection of product attributes.</td></tr><tr><td><pre data-overflow="wrap"><code>$.products[].attributes[].attribute_id
</code></pre></td><td>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.</td></tr><tr><td><pre data-overflow="wrap"><code>$.products[].attributes[].values
</code></pre></td><td>List of attributes values.</td></tr><tr><td><pre data-overflow="wrap"><code>$.products[].attributes[].values[].locale
</code></pre></td><td>Language/country combination for which the value applies (i18n localisation, e.g. en_GB or fr_FR).</td></tr><tr><td><pre data-overflow="wrap"><code>$.products[].attributes[].values[].value_id
</code></pre></td><td>Unique identifier of the attribute value (this is only required for <em>list</em> and <em>set</em> 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.</td></tr><tr><td><pre data-overflow="wrap"><code>$.products[].attributes[].values[].value
</code></pre></td><td>Value of product attribute.</td></tr></tbody></table>

#### **Example**

Two products in one locale (en\_GB) each with three attributes

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```json
{
    "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&amp;imgrefurl=https%3A%2F%2Fwww.123rf.com%2Fphoto_75391840_sexy-red-shoes-high-heels-are-on-white-background-.html&amp;docid=OKAdSxFixkXzzM&amp;tbnid=9wVZ0j8DuIgoXM%3A&amp;vet=10ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc..i&amp;w=1300&amp;h=866&amp;bih=1307&amp;biw=2560&amp;q=red%20shoes&amp;ved=0ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc&amp;iact=mrc&amp;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&amp;imgrefurl=https%3A%2F%2Fwww.123rf.com%2Fphoto_75391840_sexy-red-shoes-high-heels-are-on-white-background-.html&amp;docid=OKAdSxFixkXzzM&amp;tbnid=9wVZ0j8DuIgoXM%3A&amp;vet=10ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc..i&amp;w=1300&amp;h=866&amp;bih=1307&amp;biw=2560&amp;q=red%20shoes&amp;ved=0ahUKEwiBpo7ohfTlAhWESxUIHbuYB9kQMwi7ASgHMAc&amp;iact=mrc&amp;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&amp;ai=DChcSEwjXr7erhvTlAhWJre0KHcyWBnwYABAMGgJkZw&amp;sig=AOD64_3MBHXZueSfoJ5QCUbvLTCrRGZsvg&amp;ctype=5&amp;q=&amp;ved=0ahUKEwiPsLCrhvTlAhWloXEKHRu-BhEQvhcIag&amp;adurl="
                        }
                    ]
                },
                {
                    "attribute_id": "_thumburl",
                    "values": [
                        {
                            "locale": "en_GB",
                            "value": "https://www.google.com/aclk?sa=L&amp;ai=DChcSEwjXr7erhvTlAhWJre0KHcyWBnwYABAMGgJkZw&amp;sig=AOD64_3MBHXZueSfoJ5QCUbvLTCrRGZsvg&amp;ctype=5&amp;q=&amp;ved=0ahUKEwiPsLCrhvTlAhWloXEKHRu-BhEQvhcIag&amp;adurl="
                        }
                    ]
                }
            ],
            "locales": [
                "en_GB"
            ],
            "product_id": "p100002"
        }
    ]
}
```

{% endcode %}

{% hint style="info" %}
You do not have to supply a **locale** value for attributes with non-localisable base-types **int**, **float** and **text**.
{% endhint %}

### variants-*n*.json <a href="#dataintegrationspecification-csvproductdata-custom_attributes_meta.csv" id="dataintegrationspecification-csvproductdata-custom_attributes_meta.csv"></a>

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

<table data-full-width="true"><thead><tr><th width="469">JSONPath</th><th>Details</th></tr></thead><tbody><tr><td><pre><code>$.variants
</code></pre></td><td>Collection of all variants.</td></tr><tr><td><pre><code>$.variants[].variant_id
</code></pre></td><td>Identifier of the variant. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.</td></tr><tr><td><pre><code>$.variants[].product_id
</code></pre></td><td>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.</td></tr><tr><td><pre><code>$.variants[].locales
</code></pre></td><td>Collection of locales (i18n localisation, e.g. en_GB or fr_FR).</td></tr><tr><td><pre><code>$.variants[].attributes
</code></pre></td><td>Collection of variant attributes.</td></tr><tr><td><pre data-overflow="wrap"><code>$.variants[].attributes[].attribute_id
</code></pre></td><td>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.</td></tr><tr><td><pre data-overflow="wrap"><code>$.variants[].attributes[].values
</code></pre></td><td>List of attributes values.</td></tr><tr><td><pre data-overflow="wrap"><code>$.variants[].attributes[].values[].locale
</code></pre></td><td>Language/country combination for which the value applies (i18n localisation, e.g. en_GB or fr_FR).</td></tr><tr><td><pre data-overflow="wrap"><code>$.variants[].attributes[].values[].value_id
</code></pre></td><td>Unique identifier of the attribute value (this is only required for <em>list</em> and <em>set</em> 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.</td></tr><tr><td><pre data-overflow="wrap"><code>$.variants[].attributes[].values[].value
</code></pre></td><td>Value of variant attribute.</td></tr></tbody></table>

#### **Example**

Two products that each have two variants which are based on different colour options

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```json
{
    "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"
        }
    ]
}
```

{% endcode %}

{% hint style="info" %}
You do not have to supply a **locale** value for attributes with non-localisable base-types **int**, **float** and **text**.
{% endhint %}