Data layer specification template
A data layer specification is the contract between the people who build the site and the people who measure it: here are the events, here is what each one contains, here is when it fires. Without one, tracking depends on CSS selectors and page structure, which means every redesign breaks it silently. The document itself is unglamorous — a table of events, their parameters, types and triggers — and it's the single highest-leverage artefact in a measurement setup.
Free30 minutesNo obligation
Data layer spec · what breaks
Where teams get this wrong — Data layer spec
- 01
No specification at all
Then tracking depends on markup, and every release is a coin flip.
- 02
A spec nobody maintains
A stale spec is worse than none, because people trust it.
- 03
Reading values from the DOM instead
CSS selectors break on every redesign, silently, with no error anywhere.
Data layer spec · the fix
What a correct implementation looks like — Data layer spec
Every event named and defined
What it means, not just what it's called.
Parameters typed
String, number, array. Type errors are a real and common failure.
Trigger conditions written down
Exactly when it fires, and when it must not.
An owner and a change process
So it stays current rather than becoming folklore.
Data layer spec · architecture
What each event definition contains — Data layer spec
Six fields per event. That's enough for a developer to implement without asking, which is the only test that matters.
- 1
Event name
Exact string, lowercase snake_case. What gets pushed.
- 2
Purpose
What this event means in business terms. Prevents the wrong thing being implemented correctly.
- 3
Trigger
Precisely when it fires, and explicitly when it must not.
- 4
Parameters
Name, type, required or optional, and a realistic example value.
- 5
Source of each value
Where the developer gets it — order object, API response, user input. Never the DOM.
- 6
Validation
How to confirm it fired correctly, so QA can check it without asking anyone.
Data layer spec · diagnose
Common mistakes and how to validate each — Data layer spec
Ordered by how often we find them. Each one has a specific check rather than a general instruction to be careful.
- 01
Values read from rendered HTML
Search the container for CSS selectors. Each one is a redesign away from silently breaking.
- 02
Type inconsistency
A value sent as a string on one page and a number on another. Check a live payload on each page type.
- 03
Events that fire twice
Test a page refresh and a back-button navigation on every key event.
- 04
Spec drift
Compare the spec against a live payload. If they disagree, the spec is fiction.
- 05
No release checklist entry
Ask what happened to tracking at the last redesign. The answer is usually instructive.
Data layer spec · prove
How to prove your implementation is right — Data layer spec
Against your own records and a live payload, not against a preview screen.
Source of truth
a live data layer payload, compared field by field against the spec
- Every specified event confirmed firing on a real journey.
- Parameter types confirmed consistent across page types.
- No values read from CSS selectors.
- The spec confirmed matching live payloads, not just intentions.
- Checked on a live conversion, not in preview mode.
- Reconciled over a fully closed window, matched per record.
- Re-checked 30 days later.
Data layer spec · free audit
What we check in the free audit
- Values read from rendered HTML
- Type inconsistency
- Events that fire twice
- Spec drift
- No release checklist entry
Checked against
a live data layer payload, compared field by field against the spec
Free30 minutesNo obligation
Data layer spec · when not to buy
What this reference deliberately leaves out — Data layer spec
Stated openly, because a reference that's silent about its own gaps is the dangerous kind.
- There's no single correct data layer structure. GA4's ecommerce shape is a sensible default and yours can differ if it's documented.
- This is the specification, not the implementation. How your framework pushes to the data layer is a separate question.
- Consent state handling in the data layer is covered separately, because it has its own ordering requirements.
- Vendor documentation is the authority, not this page. Where the two disagree, the vendor is right and we'd like to know so we can correct it.
- Parameter names and behaviour change. Anything here is accurate as we last verified it; verify against the current documentation before you rely on it for a build.
Data layer spec · what we deliver
The checklist — Data layer spec
Every tracked event is in the spec
If it isn't documented, it isn't supported.
Each parameter has a name, type and example
Examples prevent more misunderstandings than descriptions do.
Trigger conditions are unambiguous
Fires on X, does not fire on Y.
Required versus optional is marked
Developers need to know what breaks if omitted.
The spec is in the release checklist
So tracking is verified before deploy, not after.
Pricing
Pick the package that fits your ad spend
Browser-side starter
$400One-time fee · lifetime ownership
Repairs and verifies your existing browser-side setup against this reference, on a live conversion.
- Implementation checked against the spec
- Verified on a live conversion
- Reconciled against your own records
- Written handover
1st-party server-side
Recommended$800One-time fee · most popular
Money events sent from your own records through a first-party container on your subdomain, built to this specification.
- First-party server container on your own subdomain
- Events from your records, not the browser
- Deduplicated on a shared event ID at every destination
- First-party cookies beyond Safari's 7-day cap
- 95%+ accuracy and 8+ Meta EMQ, guaranteed in writing
Full 1st-party stack
$1,800One-time fee · lifetime ownership
Every paid channel server-side plus the offline loop, documented to this standard.
- Everything in 1st-party server-side
- Pinterest, Snapchat, Reddit and LinkedIn CAPI
- CRM and offline conversion loop
- Refunds and cancellations corrected wherever each platform allows it
- Monitoring so the next break surfaces in days
FAQ
Data layer spec questions, answered
Ideally one named person in marketing or analytics, with developers as implementers. Shared ownership in practice means nobody maintains it.
Because CSS selectors break whenever the markup changes, silently. A data layer is a contract; the DOM is an accident of presentation.
Detailed enough that a developer can implement without asking questions. If they're asking, the spec is incomplete.
Put verification in the release checklist. A spec that isn't checked at deploy time becomes fiction within a couple of releases.
Free · 30 min
Get a data layer spec your developers can build from
WhatsAppFree30 minutesNo obligation
