Learning PathModule

Nested Attribute type

Learn how to use the AttributeNestedType to model tabular and structured Product data.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Explain when to use the AttributeNestedType for structured Product data.

  • Create a Product Type that nests another Product Type.

  • Recall the limitations and caveats of nested Attributes.

The AttributeNestedType lets you model tabular, structured data for Products. You can define a Product Type with custom Attributes and then nest that Product Type into another, composing advanced data structures from reusable building blocks. This feature is in public beta and has certain caveats to be aware of.

Use case: structured nutrition data

Consider a shop that offers food products. Many countries require nutrition facts (sugar, fat, protein quantities) for each product. A structured data object that holds nutrient information and can be reused across Products is a good fit for nested types.

A tub of ice cream with nutrition facts label.

Create the base Product Type

The objective is to construct a food-product-type that contains nutrition information captured in a Product Type called nutrient-information. The food-product-type contains a Set of nutrient-information objects (one for fat, one for sugar, and so on).
Diagram showing the food-product-type containing a nested set of nutrient-information.
Start by creating the base Product Type that you nest into the advanced Product Type. You must create the base Product Type first because you need its id to set up the reference relationship.
The nutrient-information Product Type contains two Attributes: quantityContained (a number indicating the quantity) and nutrientTypeCode (a text value for the nutrient type). Both are set as required (isRequired: true).
Nested Attributes are not searchable. Set isSearchable to false for all Attributes in the nested Product Type.
Create the nutrient-information Product Type
{
  "name": "nutrient-information",
  "description": "The nutrient-information product type.",
  "attributes": [
    {
      "name": "quantityContained",
      "type": {
        "name": "number"
      },
      "isRequired": true,
      "attributeConstraint": "None",
      "isSearchable": false,
      "label": {
        "en": "quantity contained"
      }
    },
    {
      "name": "nutrientTypeCode",
      "type": {
        "name": "text"
      },
      "isRequired": true,
      "attributeConstraint": "None",
      "isSearchable": false,
      "label": {
        "en": "nutrient type code"
      }
    }
  ]
}

Create the advanced Product Type

After creating the base Product Type, create the food-product-type by referencing nutrient-information in a nested Attribute called nutrients. Add an additional taste Attribute for a textual description.
Create the food-product-type Product Type
{
  "name": "food-product-type",
  "description": "The food product type.",
  "attributes": [
    {
      "name": "taste",
      "type": {
        "name": "text"
      },
      "isRequired": true,
      "attributeConstraint": "None",
      "isSearchable": false,
      "label": {
        "en": "taste"
      }
    },
    {
      "name": "nutrients",
      "type": {
        "name": "set",
        "elementType": {
          "name": "nested",
          "typeReference": {
            "id": "<nutrient-information-product-type-id>",
            "typeId": "product-type"
          }
        }
      },
      "isRequired": false,
      "attributeConstraint": "None",
      "isSearchable": false,
      "label": {
        "en": "food nutrients"
      }
    }
  ]
}

Create a Product with nested Attributes

With both Product Types in place, create a Product of the food-product-type. The following example creates a Product with taste set to excellent and two nested nutrient-information entries: 1.4 units of FAT and 1.15 units of SUGAR.
Diagram showing the example-food-product with nested nutrient data.
Create a Product with nested Attributes
{
  //...
  "attributes": [
    {
      "name": "taste",
      "value": "excellent"
    },
    {
      "name": "nutrients",
      "value": [
        [
          {
            "name": "quantityContained",
            "value": 1.4
          },
          {
            "name": "nutrientTypeCode",
            "value": "FAT"
          }
        ],
        [
          {
            "name": "quantityContained",
            "value": 1.15
          },
          {
            "name": "nutrientTypeCode",
            "value": "SUGAR"
          }
        ]
      ]
    }
  ]
  //...
}

How nesting works

The AttributeNestedType lets you compose advanced Product Types from existing ones. A Product Type is defined once and referenced inside an Attribute Definition of another Product Type.
Diagram showing a ProductType nested into an advanced ProductType.

The following JSON snippet shows how an existing ProductType is nested into an Attribute Definition:

{
  "name": "nestedProductType",
  "type": {
    "name": "nested",
    "typeReference": {
      "id": "<nested-product-type-id>",
      "typeId": "product-type"
    }
  }
}

Caveats

  • The feature is in public beta and is subject to change. Use it carefully in production.
  • Values of nested type Attributes are not searchable. They can't be discovered through the Product Search or the Product Projection Search API.
  • An iteration of AttributeSetType that terminates with an AttributeNestedType is limited to five steps.
  • You are allowed to nest AttributeNestedTypes into other AttributeNestedTypes, but query performance is not guaranteed for deep nesting.
  • When setting nested Attribute values on Products, you must provide all Attribute values of the nested structure. Partial updates are not supported.
  • You can't nest Product Attributes into Product Types. Nested Attributes can't be used for Product Attributes.

Test your knowledge