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: 2026-01

info:
  title: My App Tracking Plan
  version: 1.0.0

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

  events:
    key:
      minLength: 3
      maxLength: 160
      pattern: "^[a-z0-9_]+::[a-z0-9_]+$"

    x-opentp:
      keygen:
        template: "{area | slug}::{event | slug}"
        transforms:
          slug:
            - lower
            - trim
            - replace:
                from: " "
                to: "_"
            - truncate: 160
    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
        dimension_1:
          type: string
          name: orgType
          title: Organization Type
          example: enterprise

2. Create Your First Event

Create the folder structure and your first event file:

mkdir -p events/auth

events/auth/login_click.yaml

opentp: 2026-01

event:
  key: auth::login_click

  taxonomy:
    action: User clicks the login button

  payload:
    schema:
      event_name:
        value: login_click
      dimension_1:
        value: enterprise

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

Use name when a payload field key is a transport or vendor slot, but the field has a clearer logical/code-facing name. example provides a representative value for documentation, mock data, and generators.

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/2026-01/opentp.schema.json
opentp: 2026-01
...

Available schemas:

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

Next Steps

• CLI Reference — learn all available commands
• Configuration — detailed configuration options
• Transforms — string transformation pipelines
• Constraints & Rules — portable constraints and CLI checks