Schema management

Schema management lets you define and enforce the structure of your events using typed property groups. This keeps analytics clean, consistent, and easy to reason about over time.

Why schema-first tracking helps

• Prevents event drift across frontend and backend teams
• Improves dashboard reliability by enforcing consistent properties
• Makes onboarding easier with documented event contracts
• Reduces debugging time when running product experiments

A good event schema is like a public API: version it, document it, and review changes.

Event naming conventions

Use action-oriented names and keep properties explicit.

Recommended event payload

{
  "event": "user_signed_up",
  "distinct_id": "usr_12345",
  "properties": {
    "plan": "pro",
    "signup_method": "google",
    "country": "IN",
    "is_enterprise": false
  }
}

Use inline hints like distinct_id and plan consistently across all services.

Rollout checklist

1. Define the event and required properties in markdown.
2. Implement tracking in code and add tests for payload shape.
3. Validate in staging and monitor first production captures.
4. Share examples with the team and mark the schema as stable.

TypeScript helper example

type SignupEvent = {
  event: "user_signed_up";
  distinct_id: string;
  properties: {
    plan: "free" | "pro" | "enterprise";
    signup_method: "google" | "email" | "github";
    country?: string;
  };
};
 
export function trackSignup(client: { capture: (event: SignupEvent) => void }, payload: SignupEvent) {
  client.capture(payload);
}

Common mistakes to avoid

• Sending optional fields with inconsistent types (for example is_paid as both string and boolean)
• Renaming properties without a migration plan
• Capturing sensitive personal data accidentally
• Tracking too many low-signal events

For implementation details, see PostHog docs.