Event Schema

A portable, typed YAML format for declaring product analytics events — what events your app fires, what they carry, and what each one means. Codegen, validation, and agents read this file to understand your event schema without grepping source code.

Paste to your agent

Declare this codebase's analytics events in event-schema.yaml so every track() call is type-checked at build time.

Read https://clamp.sh/docs/event-schema and https://clamp.sh/docs/sdk/tracking#typed.

1. DISCOVER. Run `rg -n "track\(" --type ts --type tsx --type js --type jsx` and similar greps for the SDK in use (analytics.track, posthog.capture, mixpanel.track, amplitude.track, etc.). Build a table of: event name, call sites, observed properties, and which properties appear in EVERY call (those are required) vs only some (optional). Do not invent events.
2. CHECK for an existing event-schema.yaml at the repo root. If it exists, treat this as an update pass: keep declared events whose call sites still exist; flag events declared but no longer fired; flag events fired but not declared.
3. ASK ME for one-sentence intent on every ambiguous event name (e.g. `feature_used`, `engagement`, `event_42`). Batch the questions in one message. Skip events whose name is self-explanatory (`page_viewed`, `signup_completed`, `checkout_completed`) and draft intent yourself. Do not fabricate intent — "Generic engagement event" is worse than no intent.
4. WRITE `event-schema.yaml` at the repo root. Use `version: "0.1"` (the version string MUST be quoted; unquoted parses as a number). Use only the supported property types: `string`, `number`, `boolean`, `enum` (with `values: [...]`), `money`. For enums, declare ONLY the values you actually saw in the codebase. Do not speculatively add values.
5. VALIDATE. Run `npx @clamp-sh/event-schema validate` and fix any errors before continuing.
6. GENERATE. Run `npx @clamp-sh/event-schema generate`. This writes `event-schema.d.ts` next to the YAML.
7. WIRE the generated type into the SDK. For @clamp-sh/analytics: change the init call to `init<AnalyticsEvents>("proj_...")` once at app start, then every existing `track()` call across the codebase is type-checked. For other SDKs that don't accept a generic, write a 3-line typed wrapper (`function track<K extends keyof AnalyticsEvents>(event: K, props: AnalyticsEvents[K])`). Do not refactor every call site if a one-line wrapper does the job.
8. VERIFY. Run `tsc --noEmit` (or the project's typecheck script). Fix any newly-surfaced type errors at call sites — these are real bugs the schema just caught.
9. ASK ME if you should add `event-schema validate` to a precommit hook or CI step so the schema can't silently drift from call sites in future PRs.
10. Stop and report: every event declared (name + intent + properties), the SDK wiring change, and any type errors found and fixed at step 8.

Why declare a schema

Most product analytics tools treat event schema as tribal knowledge. Property names live in code comments, internal wikis, or Slack threads. AI agents asking “what does cta_click carry?” have to grep your codebase. Renames mean manual sweeps across hundreds of call sites. A declarative event-schema file fixes all three:

• Discoverable. Agents and humans read the file instead of grepping.
• Refactor-safe. Rename a property in one place, regenerate types, TypeScript surfaces every broken call site at build time.
• Durable. The intent of each event survives past the conversation that produced it — for new agents, new teammates, and the original author six months later.

Install

# One-off
npx @clamp-sh/event-schema generate

# Or as a dev dependency
npm install --save-dev @clamp-sh/event-schema

Auto-discovers event-schema.yaml from the current directory or any parent and writes the generated types alongside it. See Commands for output options.

Quick start

Author event-schema.yaml at your project root:

version: "0.1"

events:
  signup_completed:
    intent: |
      Primary conversion event — account creation succeeded.
    properties:
      plan:
        type: enum
        values: [free, pro, growth]
        required: true
      method:
        type: enum
        values: [email, github]
        required: true

  cta_click:
    intent: |
      Top-of-funnel engagement signal — which CTA earned the click.
    properties:
      location:
        type: string
        required: true
        examples: [hero_primary, nav_signup, final_cta]
      destination:
        type: string
        required: true

Generate types:

npx event-schema generate

Writes event-schema.d.tsnext to the source. Use it with the SDK’s typed-events generic:

import { track } from "@clamp-sh/analytics";
import type { AnalyticsEvents } from "./event-schema";

track<AnalyticsEvents>("signup_completed", { plan: "pro", method: "email" });
//                       ^ event name + properties type-checked at compile time

TypeScript will catch typo’d event names, missing required properties, wrong property names, and wrong value types — all at build time, before any event ever fires.

Format

Top-level fields are version and events. Each event has an optional intent(one sentence on what it’s for) and a required properties object.

Each property may also declare required: true (defaults to false), description (carried into the generated JSDoc), and examples: [...] (sample values, surfaced as @example in the JSDoc — purely informational, not validated).

Full format definition lives in the spec on GitHub.

Commands

event-schema validate
event-schema generate

validatechecks the schema against the spec’s meta-schema and exits non-zero on errors. generate emits a TypeScript declaration. Both auto-discover event-schema.yaml (or .json) by walking up from the current directory; pass an explicit path to override.

Options for generate

Examples

The spec repo includes three canonical examples — minimal, SaaS-flavored, and ecommerce (with the money type) — each pairing the input YAML with the TypeScript the CLI produces:

• minimal — single event, single property
• saas — multi-event with empty-properties events and enums
• ecommerce — money type and quantities

Status

Spec version 0.1. The format is in active dogfood; the design may change before reaching 1.0. The reference CLI (@clamp-sh/event-schema) implements the full spec. Source and the spec itself live at github.com/clamp-sh/event-schema.