Tracking catalog

Keep one catalog of events, properties and rules per app: edit it as a list, import it from your taxonomy sheet, see what flows check.

Each app has one catalog file in the workspace, for example tracking-specs/mydmv.yaml. It holds the rules every run is checked against: which events exist, their properties and allowed values, and the general rules. What a single flow expects is not here: that lives in the flow, in assertEvents steps. See Tracking.

To start a new catalog, choose File → New File… (⇧⌘N), pick Tracking Catalog and name it after the app. Scout creates tracking-specs/<name>.yaml with no events yet and opens it as a catalog: use Import… to fill it from your taxonomy sheet, or + → Event under the list to enter events by hand.

Open a file under tracking-specs/ and use the switch in the jump bar:

View	Use it for
Catalog	Edit events, user properties, enums and rules without writing YAML
YAML	Edit the text directly, or anything the catalog view does not cover

Scout remembers the choice for each file. The YAML stays the source of truth: the catalog view changes only the lines you touch, so comments and blank lines survive.

A YAML error

The catalog view shows a banner with the error and its line. Click Open YAML at line N, fix it, and switch back.

The catalog view

The list is on the left, the detail of the selected item on the right. The bar at the bottom sums up the file, for example "spec valid · 34 events · 21 enums · used in 3 flows".

• Filter. The Filter field in the bar under the list filters by event, property, enum or value.
• Groups. Events, User properties, Enums and General rules.
• Add and remove. The + menu adds an Event, User Property or Enum, or a general rule from a template. − removes the selected one after a confirmation. An enum that properties still use cannot be removed; the message names them.
• Remove an event that flows check. Scout warns "This event is checked in N places in flows", and still removes it if you confirm.

Events

An event is one form, from top to bottom:

Part	Meaning
Title row	The event name, renamed in place. Scout renames the event everywhere it appears in the catalog (rules, cross checks, login event) and asks first, with the number of places. It does not rename events inside flow files. "Not seen in any run yet" shows next to it when a run exists that never saw the event
Description	Add Description… shows while it is empty
Properties	Values from run at the top picks the run the event is compared with; the values and suggestions come from it. Then one row per property: its name, "type · Required" or "type · Optional", and on the right the allowed values in words ("Any" when nothing is checked, a pattern in monospace, "≥ N" for a number). A status icon marks a property the last run broke. The chevron (Edit) opens the property. Add Property… is under the list. The footnote says a property that breaks its rule fails the run
Properties not in this list	What a run does when the app sends a property the event does not list: Follow general rule (Warning), Ignore, Warning or Error
Checked in flows and Forbidden in the flow header	Where flows check or forbid this event, see below. Hidden when empty
Related rules	The general rules that name this event, as sentences. Click one to edit it

Click the chevron of a property to edit it in a popover: its name, Type, Required, the allowed values, and Remove Property. A property shared by several events (a YAML anchor) shows a link icon; when you edit it, Scout asks Edit all N events or Edit only this event (make a separate copy).

Allowed values

In the popover of a property, the allowed-values editor picks how its value is checked:

Mode	Checks that the value
Shared enum	is in a named list from Enums. Pick the list from a menu; editing the values changes every property that uses it ("Used in N properties")
Own list	is in a list that only this property has. New enum from this list turns it into a shared enum
Regex	matches a pattern. A bad pattern is flagged
Number ≥	is a number at least this big
Anything	any value passes

Split into an own list copies a shared enum's values into this property, so you can change them without touching the others.

Suggestions from a run

With a run captured, an event also lists what the run showed:

Suggestion	Action
New value of an enum property	Add to allowed values, or It is an app bug to dismiss it
Property the event does not list	Add, or fix the app
Required property missing	Fix the app, or make the property optional

User properties and enums

• User properties and Enums use the same form style as events. User properties have a Type, Allowed values (the same editor as events), When wrong (Default (general rule), Ignore, Warning, Error) and Needs team confirmation.
• Enums list their values: add, change or remove one, or paste several lines for several values. Needs team confirmation keeps a value list the team has not agreed on yet at warning level. Used in shows the properties that use the enum. A list that differs per platform shows "Per platform: edit in the YAML", with Open YAML.

Checked in flows

Every event with flow checks shows Checked in flows with the number of places: each file:line where a flow's assertEvents names it, with the values written there. Click a row to open the flow at that line. Forbidden in the flow header lists flows that name the event in tracking.forbid. Both sections are hidden when empty.

General rules

General rules hold what is not tied to one event. Each rule reads as a sentence with its severity, for example:

• Same paywall id, placement in Paywall Viewed and Paywall Skipped · error
• If Purchase Completed has is trial = true then Home Screen Viewed has access level = trial · warning · needs confirmation
• step number of Onboarding Step Viewed counts up from 1, +1 each time
• Application Opened must not appear · error
• lesson_id is a wrong name, the right one is lesson id

The rule groups are Unknown and forbidden events, Property names, Unknown properties and user properties, Data types, Cross checks, User properties by event, Login, Amplitude profile, Server checks and iOS/Android parity. The last four are described in Tracking.

Add a rule

Click + under the list and pick a template under General rule. You never type a rule: every choice comes from the catalog.

Template	Writes
Same value across events	The listed properties must have the same value in all the listed events
If … then …	If an event has a property value, another event must have a property value
Counts up each time	A numeric property goes up by a step on every event, from a start value
Event must not appear	The event is never allowed
Allow event outside the catalog	An event that is not in the catalog is accepted, with no warning
Common wrong property name	Names a wrong spelling and the right one

The popover has the event and property pickers (a Pick a name menu), When wrong (Error or Warning only) and Needs team confirmation. Save stays locked, with the reason shown, until every field is filled. Click an existing rule's sentence to edit it in the same popover, or Remove it.

Try on the run at 14:02 runs the draft against the newest run before you save and tells you what would pass or fail. It is hidden when there is no run.

Severities

Severity	Effect
Error	The check fails and the run fails
Warning	Recorded in the report, the run does not fail
Ignore	Not checked

A rule marked Needs team confirmation runs as a warning until someone clears the mark.

Events the catalog lacks

An event the app sends that the catalog does not list follows Unknown events in the general rules (warning by default). The list shows them under App sends, catalog lacks · N, with how often and in which run. Click Add to catalog to create the event from what the app sent.

The other way round: turn on Not checked by any flow, the ◇ button at the end of the Filter field. It leaves only the events no flow checks.

A flow check that names an unknown event offers the same fix from the flow: see Quick fixes.

Import your taxonomy

If your team keeps the event plan in a spreadsheet, let Scout fill the catalog from it instead of typing.

1. Download the sheet as .xlsx, or each tab as .csv or .tsv. (Old .xls, .numbers and links to a Google Sheet are not read.)
2. In the catalog view, click Import… in the jump bar.
3. Click Choose File… and pick the file. For csv or tsv you can pick the tabs together.
4. Pick Event name: Display (the display column, the default) or Ingested.
5. Review the list, untick what you do not want, and click Write to catalog.

What Scout reads

Scout finds each tab by its column headers, not by the tab name:

Tab	Needs columns
Events	Event Name (Display) (or Ingested Name) and Event Properties
Event properties	Property Name, Data Type, Used By Events
User properties	Property Name, Data Type, and Set By Events or Source

Group title rows are skipped. A missing Events tab or column is reported in a list of problems; fix the sheet and choose the file again. A missing property tab only means that part is not compared.

What the sheet shows

Section	Contains
New events and properties	In the sheet, not in the catalog
Changed events and properties	In both, but different: a new property, or a different type
Removed from the sheet	In the catalog, no longer in the sheet
Skipped	Events sent by the backend (check them with server checks), events the SDK sends itself, and user properties Amplitude sets. They have no tick box

Click a row to see the lines it will write under Preview. Show N more lists the rest of a long section.

What is pre-ticked

Item	Ticked	Why
Plain new or changed items	Yes	Safe to take as is
Items that need confirmation	No	The sheet gives enum values only as samples, a type is empty, a property has several definitions, or a name appears twice. Tick them once the team agrees. Values taken from samples are saved as an enum marked Needs team confirmation
Removed events nothing uses	Yes	The catalog follows the sheet
Removed events that a flow checks or a rule names	No	Removing them would break a flow or a rule. The row says where they are used

A new property is written as required, except one the sheet marks iOS-only or Android-only. The import never overwrites what you added by hand: regex, severity, required, not_empty, minimum, confirmed enums and comments stay. Allowed values that the sheet adds to an existing enum are added; none are removed.

Writing and changing files

• The server writes the catalog, so ⌘Z does not undo it. Fix it in the YAML view if needed.
• If the catalog file changed while the sheet was open, Scout reads it again and re-checks the sheet. Your ticks stay on the items that did not change; an item whose content changed becomes unticked so you can look at it again.

Engine rules worth knowing

• One definition per event. The same event name twice under events: is a YAML error, and the catalog does not open until one is removed.
• Strict global_rules. An unknown key under global_rules is a parse error, so a misspelled rule is never ignored silently. A property whose enum_ref names an enum that does not exist is also an error.
• language_independent_values. Add language_independent_values: { severity: error } under global_rules to catch translated values. A string value of a property with an enum, outside that enum and with non-ASCII letters (for example 车 for car), fails at that severity. This holds even for a confirmed enum.
• Cross checks have a severity. same_value, increasing_sequence and implies take severity (error or warn; the default is error, and needs_confirmation lowers it to a warning). A same_value group that lists Paywall Viewed starts over at each Paywall Viewed.
• No scenarios. A catalog with scenarios, shared_cross_checks, flow_id or global_rules.unexpected_events is rejected. Use assertEvents in flows and global_rules.unknown_events.

spec_version: 2
global_rules:
  unknown_events:
    severity: warn
    allowed: ["[Amplitude] Application Installed", "$exposure"]
  language_independent_values:
    severity: error
cross_checks:
  - { rule: same_value, properties: [paywall id, placement], across: [Paywall Viewed, Paywall Skipped] }
  - { rule: increasing_sequence, event: Onboarding Step Viewed, property: step number, start: 1, step: 1 }
  - rule: implies
    needs_confirmation: true
    if:   { event: Purchase Completed, property: is trial, equals: true }
    then: { event: Home Screen Viewed, property: access level, equals: trial }

An enum and a property that uses it:

enums:
  license type:
    values: [car, cdl, motorcycle]
events:
  License Selected:
    properties:
      license type: { type: string, required: true, enum_ref: license type }

From a terminal or plugin

Agents and scripts use the same operations over HTTP on the Studio server:

Route	Does
GET /api/tracking/spec?workspacePath=…&path=…	Returns the YAML, its hash and the model the catalog view uses
POST /api/tracking/spec/edit	Applies set, insert, remove, move or rename ops on a path. baseHash must match the file, or the answer is 409; an invalid op or resulting catalog returns 422
POST /api/tracking/spec/suggest	Returns suggestions from a run, without writing the file
POST /api/tracking/spec/try	Applies ops in memory and returns the checks of a run that change, without writing the file
POST /api/tracking/spec/rename-event	Renames an event and all its references in one edit
GET /api/tracking/spec/usages	Returns where flows check each event
GET /api/tracking/coverage	Returns events no flow checks, and events the app sent that the catalog lacks
POST /api/tracking/import/preview, /import/apply	Preview and write a taxonomy import

The request and response fields are listed in flows/mydmv/tracking-specs/README.md in the repository.