# Full Feed JSON Data Format

## 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://crownpeak.gitbook.io/product-discovery/sending-and-managing-product-data/flatfiles/fullprodfeed/full-feed-json-data-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.