Getting Started

Getting Started

Installation

macOS / Linux:

curl -fsSL https://opentp.dev/install | bash

Windows (PowerShell):

irm opentp.dev/install.ps1 | iex

npm:

npm install -g opentp

npx (no install):

npx opentp validate

Quick Start

1. Create opentp.yaml

Create a configuration file in your project root:

opentp: 2025-12

info:
  title: My App Tracking Plan
  version: 1.0.0

spec:
  paths:
    events:
      root: /events
      pattern: "{area}/{event}.yaml"
    dictionaries:
      root: /dictionaries

  events:
    key:
      pattern: "{area | slug}::{event | slug}"
    taxonomy:
      area:
        title: Area
        type: string
        required: true
      event:
        title: Event
        type: string
        required: true
      action:
        title: Action
        type: string
        required: true
    payload:
      targets:
        all: [web, ios, android]
      schema:
        event_name:
          type: string
          required: true

  transforms:
    slug:
      - lower
      - trim
      - replace:
          from: " "
          to: "_"
      - truncate: 160

2. Create Your First Event

Create the folder structure and your first event file:

mkdir -p events/auth

events/auth/login_click.yaml

opentp: 2025-12

event:
  key: auth::login_click

  taxonomy:
    action: User clicks the login button

  payload:
    schema:
      event_name:
        value: login_click

Note: taxonomy fields referenced in spec.paths.events.pattern (e.g. area, event) are extracted from the file path, so you don’t need to duplicate them in event.taxonomy.

3. Validate

Run validation to check your tracking plan:

opentp validate

Expected output:

✓ All events are valid count=1

Project Structure

A typical OpenTrackPlan project looks like this:

my-tracking-plan/
├── opentp.yaml                 # Main config
├── events/                     # Event definitions
│   └── {area}/{event}.yaml
└── dictionaries/               # Reusable enums
    ├── taxonomy/
    │   └── areas.yaml
    └── data/
        └── application_id.yaml

IDE Support

Add JSON schema references for autocompletion:

# yaml-language-server: $schema=https://opentp.dev/schemas/2025-12/opentp.schema.json
opentp: 2025-12
...

Available schemas:

• https://opentp.dev/schemas/2025-12/opentp.schema.json — main config
• https://opentp.dev/schemas/2025-12/event.schema.json — events
• https://opentp.dev/schemas/2025-12/dict.schema.json — dictionaries

Next Steps

• CLI Reference — learn all available commands
• Configuration — detailed configuration options
• Transforms — string transformation pipelines
• Checks — field validation checks