Flat vs. Nested Data Layer

Tealium Employee

Since data is the foundation for the Tealium solution, setting up a consistent data layer is a vital first step for implementation. The data layer defines attributes about your website or mobile app, such as country code or page name, as well as important user behaviors to track, such as logins and purchases.

When adding a data layer to your existing codebase, Tealium’s best practice is to use a flat JavaScript data object called utag_data or the Universal Data Object (UDO). Tealium recommends a flat data layer for most implementations because the flat structure is easier to read, reference and maintain for users of various technical abilities.

Flat vs Nested Objects

A flat object contains one level of properties or “key: value” pairs. The alternative is a nested data object, which has multiple levels of data, or sub-objects, which can be arbitrarily complex. Either a flat or nested data layer can be used within Tealium. Here is an example of a flat object from a shopping cart page and the equivalent nested object:

Flat Object

Nested Object

var utag_data = {

   page_ name         : “Shopping Cart”,

   page_category      : “checkout”,

   cart_total_items   : “2”,

   cart_total_value   : “31.98”,

   product_id         : [“PROD123”],

   product_name       : [“Red T-Shirt”],

   product_quantity   : [“2”],

   product_unit_price : [“12.99”],

   product_list_price : [“15.99”],

   product_discount   : [“0.00”]


var digitalData = {

   page : {

       name : “Shopping Cart”,

       category : “checkout”


   cart : {

       total_items : “2”,

       total_value : “31.98”,

       items : [


              id : “PROD123”,

              name : “Red T-Shirt”,

              quantity : “2”,

              price : {

                  unit : “12.99”,

                  list : “15.99”,

                  discount : “0.00”






Let’s use the objects above to demonstrate why the flat version - utag_data - is easier to reference. In this example, we’ll reference the first product ID from the data layer.

Flat Object: utag_data.product_id[0]

For the flat object, since all the key value pairs are on one level, we start by referencing the name of the object (utag_data), followed by the key (product_id). Since we are looking for the first product ID only, we’ll return the first value (or index 0) instead of the entire array.

Nested Object: digitalData.cart.items[0].id

The first two steps are the same for the nested format - reference the name of the object (digitalData) and the first key (cart) - however, we need to continue traversing the object to find the first product ID. Inside of the cart object, we are looking for the first value of the items array (items[0]). This returns a sub-object, where we want to reference the key (id).

With the nested format, we traversed multiple levels or sub-objects in order to find the product ID, whereas with the flat object, the product ID was available at the first level. This example necessitated two extra levels for the nested object, but it could be infinitely more complex and require basic coding knowledge, depending on what information is needed from the data layer.

If you are implementing a data layer for the first time, we advocate choosing a flat object. This format helps you see the most benefit from Tealium’s solution and enables time-saving features such as the e-commerce extension. In partnering with hundreds of clients, we’ve found that nested data layers tend to be more difficult to create, reference and troubleshoot, especially for those unfamiliar with object-orientated programming. Below is an outline of the pros and cons to each type of data layer.


Flat Data Layer

Nested Data Layer


+ Simple
+ Readable

+ Consistent variable names

+ Easy to implement within Tealium

+ Fewer lines of code

+ Less potential for error

+ Flexible

+ Can meet W3C specification

+ Technical team may be more familiar with an object-oriented approach


- Doesn’t meet W3C specification

- Less consistent variable names

- Less readable, especially to non-technical team members

- Adds complexity within Tealium

- Increases error potential

- Long-term maintenance is more difficult

- Dealing with unfamiliar data objects is more challenging for new team members and the Tealium support team

Using a Nested Data Layer

While we often recommend using a flat object, a nested data layer may be the best decision for your organization, and you can use this option within Tealium.

If your team has invested heavily in a nested data layer, it might not be prudent to reformat the object, especially when key vendors or internal teams depend on the current data structure. Also, technical resources may not be available to transform the existing nested data layer into a flat object. Either way, we can use your existing nested data layer, converting it to a flat object with Tealium to meet our specifications.

We recommend reviewing the information in your nested data layer, even if you already have one defined, to determine if there are any instances of too much or too little data. When there is too little data, more data might be needed to accomplish your use case. Too much data can lead to the same or similar data existing multiple times in a nested data layer and you will want to make sure to standardize which data points should be used. Collecting and standardizing the right data is key to implementing and maintaining the Tealium solution.

Here is more information on how to convert a nested data layer into a flat object within Tealium: https://community.tealiumiq.com/t5/iQ-Tag-Management/Data-Layer-Converter/ta-p/17581

8 Kudos