Launch Observer — UAT Assertions Guide

1. File structure

Every UAT configuration is a JSON file with a site identifier and an array of assertion rules.

Required keys

siteId (string), assertions (array)

Optional keys

siteName (string), global gates, per-assertion title and description

Global gates (optional)

Use global to include or exclude UAT by service ID and payload-based conditions.

includeServices: only run UAT for these services.
excludeServices: never run UAT for these services.
includeConditions: all must pass to run UAT.
excludeConditions: any match skips UAT.

{
  "siteId": "example-site",
  "siteName": "Example Site",
  "global": {
    "includeServices": ["adobe-analytics", "adobe-edge"],
    "excludeServices": ["meta"],
    "excludeConditions": [
      {
        "source": "payload",
        "path": "events[0].xdm.eventType",
        "operator": "equals",
        "expected": "web.webinteraction.linkClicks"
      }
    ]
  },
  "assertions": [
    {
      "id": "pageview-once",
      "title": "Pageview fires only once",
      "conditionsLogic": "all",
      "conditions": [
        {
          "source": "payload",
          "path": "events[0].web.webPageDetails.siteSection",
          "operator": "equals",
          "expected": "Homepage"
        }
      ],
      "validations": [
        {
          "source": "payload",
          "path": "events[0].xdm.eventType",
          "operator": "equals",
          "expected": "web.webpagedetails.pageViews"
        }
      ],
      "scope": "page",
      "count": "exactly",
      "value": 1
    }
  ]
}

1.1 Service catalog (IDs)

Use these IDs in global.includeServices or global.excludeServices.

adobe-edge — Adobe Edge
adobe-analytics — Adobe Analytics
google-analytics — Google Analytics
google-ads — Google Ads
meta — Meta Pixel
tiktok — TikTok Pixel
linkedin — LinkedIn Insight
pinterest — Pinterest Tag
snapchat — Snapchat Pixel
x — X Ads
microsoft-ads — Microsoft Ads (Bing)
baidu — Baidu Tongji
demandbase — Demandbase
hotjar — Hotjar
segment — Segment
mixpanel — Mixpanel
amplitude — Amplitude

2. Assertion fields

Assertions describe what should be true for a request or a page.

Field	Type	Required	Notes
id	string	Yes	Unique identifier for the rule.
title	string	No	Displayed in UI and reports.
description	string	No	Helpful context for teammates.
conditionsLogic	"all" \| "any"	No	Defaults to all (applies to conditions only).
scope	"request" \| "page"	No	Defaults to request.
conditions	array	No	Applicability filters (when the assertion should run).
validations	array	Yes	All validations must pass when applicable.
count	"exactly" \| "at_least" \| "at_most"	Only if scope=page	Use with value.
value	number	Only if scope=page	The expected count.

Validations always use all logic (there is no override).

3. Condition fields

Condition objects are used in both conditions (applicability) and validations (checks that must pass).

Field	Type	Required	Notes
source	"payload" \| "query" \| "headers" \| "raw"	No	Defaults to payload.
path	string	Yes (unless source=raw)	Dotted path or array index (e.g. `events[0].xdm.eventType`).
operator	string	Yes	See operators table below.
expected	string \| number \| array	Required for most operators	Not needed for exists or not_exists.

4. Operators reference

Use operators to express equality, matching, and numeric comparisons.

Operator	Description	Expected type
exists	Value is present and not empty.	None
not_exists	Value is missing or empty.	None
equals	Exact match.	string/number
contains	Value includes substring.	string
starts_with	Value starts with substring.	string
ends_with	Value ends with substring.	string
regex	Value matches regex.	string (regex)
in	Value is one of expected list.	array
not_in	Value is not in expected list.	array
gt	Greater than.	number
gte	Greater than or equal.	number
lt	Less than.	number
lte	Less than or equal.	number
range	Between min and max (inclusive).	array [min, max]

5. Scope + count rules

Request scope checks a single request; page scope validates the total count of matches per page view.

Request scope

Validates the current request only. Use for event types, query params, headers, and payload values.

Page scope

Validates how many matching requests occurred on the same page. Use with count and value.

{
  "id": "pageview-once",
  "conditionsLogic": "all",
  "conditions": [],
  "scope": "page",
  "count": "exactly",
  "value": 1,
  "validations": [
    {
      "source": "payload",
      "path": "events[0].xdm.eventType",
      "operator": "equals",
      "expected": "web.webpagedetails.pageViews"
    }
  ]
}

6. Practical examples

Copy and adapt these patterns to your own analytics signals.

Query parameter equals

{
  "id": "config-id",
  "conditionsLogic": "all",
  "conditions": [],
  "validations": [
    {
      "source": "query",
      "path": "configId",
      "operator": "equals",
      "expected": "abc123"
    }
  ]
}

Header exists

{
  "id": "content-type",
  "conditionsLogic": "all",
  "conditions": [],
  "validations": [
    {
      "source": "headers",
      "path": "content-type",
      "operator": "exists"
    }
  ]
}

Raw body contains

{
  "id": "raw-contains",
  "conditionsLogic": "all",
  "conditions": [],
  "validations": [
    {
      "source": "raw",
      "path": "",
      "operator": "contains",
      "expected": "pageName"
    }
  ]
}

Any conditions example

{
  "id": "event-type-any",
  "conditionsLogic": "any",
  "conditions": [
    {
      "source": "payload",
      "path": "events[0].web.webPageDetails.siteSection",
      "operator": "equals",
      "expected": "Homepage"
    },
    {
      "source": "payload",
      "path": "events[0].web.webPageDetails.siteSection",
      "operator": "equals",
      "expected": "Landing"
    }
  ],
  "validations": [
    {
      "source": "payload",
      "path": "events[0].xdm.eventType",
      "operator": "equals",
      "expected": "web.webpagedetails.pageViews"
    },
    {
      "source": "payload",
      "path": "events[0].xdm.eventType",
      "operator": "equals",
      "expected": "web.webinteraction.linkClicks"
    }
  ]
}

7. Best practices

Start with a template and remove what you don’t need.
Keep IDs stable so your reports remain consistent.
Use page-scope rules sparingly for unique events (pageviews, first-load events).
Prefer exists for required fields, then add equals for critical values.

UAT assertions: complete configuration guide