Governance

Realanalytics treats your analytics schema as code. The governance layer adds validation, diffing, and visibility to ensure schema changes are safe and intentional.

Lint your schema

Run realanalytics lint to validate your analytics definitions before deploying.

npx --no-install realanalytics lint

The linter checks for:

The property check does not cover two cases. Built-in events such as $pageview declare their properties as SDK types only, so lint cannot check them at runtime. Properties that start with $ are reserved SDK and platform properties, such as first-touch and consent fields. Ingest accepts them on every event.

Deploy diffs

realanalytics deploy and realanalytics deploy --dry-run show one structured diff against the current deployment: events, dashboards, attribution configs, and breaking changes. A dry run shows exactly what the same deploy would persist.

$ npx --no-install realanalytics deploy --dry-run

  Dry run — nothing was persisted.

  Deploy Diff:

    Events:
      [+] checkout_started
          [+] cart_value (number)
          [+] item_count (number)
      [~] signup_completed
          [+] referral_source (string)
          [-] legacy_field

    Dashboards:
      [~] overview
          [~] widget: conversion_funnel
          [+] widget: checkout_metrics

    Attribution (path-level definition diff):
      [~] default v2 -> v3
          [~] model: "last_touch" -> "position_based"
          [~] lookbackWindowDays: 30 -> 60
          [+] attio.stageByValue["Closed Won"]: "customer"
          [~] destinations.meta: false -> true

  ⚠ Breaking Changes:
    [!] signup_completed.legacy_field: Property removed but still referenced by dashboard widgets: overview/plans (breakdownBy)

A breaking change is an event that a widget still references, or a property that a widget still reads, that the deploy removes or retypes. The check uses the same references as lint: breakdowns, widget filters, funnel step filters, and every series event. Each warning names the affected dashboard/widget. A dry run exits with code 1 when it finds breaking changes.

Attribution changes

Every deploy includes an attribution section. A deploy activates at most one attribution config: the definition in analytics/attribution.ts.

• [+] added: no active config has this id. The deploy creates the next version of the id and lists every definition path.
• [~] modified: the definition changed. The active version is retired, the next version is created, and each changed path is listed with its old and new values.
• [-] removed: the active config is retired because attribution.ts was deleted, or because the deploy activates a different attribution id.
• [=] unchanged: the definition matches the active version, which stays active. An unchanged config alone does not count as a change.

Paths address fields of the attribution definition, for example model, lookbackWindowDays, positionWeights.first, destinations.meta, meta.stages, conversionEvents.lead_submitted.stage, and attio.stageByValue["Closed Won"]. Lists such as meta.stages are compared as whole values.

Event Catalog

The Event Catalog page (/{projectId}/catalog) shows all defined events from your latest schema deployment. Access it from the sidebar in any dashboard.

The catalog shows:

• All event names with descriptions
• Properties with types and required status
• Which dashboards reference each event
• Autocapture and conversion badges
• Deploy history with expandable diffs

Schema versioning

Every deploy creates a versioned schema snapshot. The deploy history timeline stores the same diff the deploy printed: field-level event diffs, dashboard changes, attribution config versions with their changed definition paths, and breaking change warnings. Deploys recorded before attribution diffs were added show no attribution section.

Next Steps

• CLI commands reference
• Event Debugger
• Defining dashboards