LEVEL Agency
Measurement Docs

Google Tag Manager

DataLayer Conventions

Keeping an organized and well-formed dataLayer is an important part of modern web and application measurement. You'll find a few guidelines/tips here on how to format dataLayer.push() payloads.

If given the choice (either when implementing or providing a spec) we highly recommend following the conventions highlighted here. However, there will be unavoidable circumstances where events emitted by 3rd party systems/integrations do not follow the recommendations in this article.

Event Namespaces

What is a namespace? Think of a namespace as a digital area code that prevents confusion between similar events.

By naming an event lvl.form_submit instead of form_submit, it clearly shows which system "owns" the event (or where it originated from). This prevents conflicts when multiple systems track similar activities. Additionally, when combined with well formed event names, namespaces can also enable dynamic tagging configuration.

Adopting a namespace strategy is a good practice for abstract dataLayer events. However, we do not recommend their use on the event names pushed into analytics/measurement platforms.

Nested vs. Flat Payloads

For non-trivial event payloads, we recommend using a nested structure.

There are a couple reasons for this:

  1. It is easier to transform a nested structure into a flat one when necessary than transforming a flat structure into a nested one.

  2. It keeps your data semantically structured which can help with QA and automated testing.

Nested Example

 1dataLayer.push({
 2  event: 'lvl.form_submit',
 3  form: { 
 4    id: '4839',
 5    provider: 'marketo:ABC-123-DEF',
 6    group: 'demo_request',
 7    fields: {
 8      first_name: 'Big',
 9      last_name: 'Bird',
10      email: '[email protected]',
11      phone: '(410) 241-1062',
12    } 
13  }
14});

Take the example above of a well-formed form_submit event. The data is easy to scan, and is organized hierarchically. Additionally, entire trees/sections of the data (e.g. form.fields) can be handled differently during transformations without having to know every payload property in a flat structure.

Flat Example

 1dataLayer.push({
 2  event: 'lvl.form_submit',
 3  form_id: '4839', 
 4  form_provider: 'marketo:ABC-123-DEF',
 5  form_group: 'demo_request',
 6  first_name: 'Big',
 7  last_name: 'Bird',
 8  email: '[email protected]',
 9  phone: '(410) 241-1062', 
10});

For simple events with a shallow amount of data, a flat structure can be fine. But, this can fall apart quickly when trying to use the data in situations where a more dynamic approach (looping and transforming) may be necessary.

Property Casing

As mentioned in our naming conventions, it is recommended to use `snake_case` for all payload properties (when providing a spec or impementing a custom event).

© 2026 Level Agency.