Canonical KPI Definition Template (Interactive)

{ "Title": "Canonical KPI Definition", "IntroductionHtml": "

Use this form to capture a complete, unambiguous definition for a metric or KPI. Include precise calculation details, data lineage, owner, tolerances, and known limitations so teams can reliably measure, trust, and act on this measure.

Help text beside each field gives examples and guidance. Save definitions to the shared metric catalog so others can reuse, review, and link dashboards or alerts.

", "SubmitLabel": "Save KPI definition", "SuccessMessage": "KPI definition saved. You can update it anytime or copy it into a shared metric catalog.", "DataType": "KPI_Definition", "SchemaVersion": "1.0", "Fields": [ { "Key": "metric_name", "Type": "text", "Label": "Metric name", "HelpText": "Concise, unique name. Prefer noun-verb or clear metric phrasing (e.g., 'Checkout Conversion Rate', 'Mean Time to Repair'). Avoid ambiguous abbreviations.", "Required": true }, { "Key": "short_description", "Type": "textarea", "Label": "Short description", "HelpText": "One or two sentences describing what the metric measures and why it matters.", "Required": true }, { "Key": "business_intent", "Type": "textarea", "Label": "Business intent and decision tied to metric", "HelpText": "What decisions, actions, or outcomes should this metric guide? Example: 'Used by product managers to decide when to prioritize checkout flow improvements.'", "Required": true }, { "Key": "exact_calculation_formula", "Type": "textarea", "Label": "Exact calculation / formula", "HelpText": "Provide a clear formula, numerator/denominator, aggregation method and time window. State units (percentage, count, seconds). Example: 'Checkout Conversion Rate = (completed_checkouts / visits_with_cart) * 100 over 28-day rolling window.'", "Required": true }, { "Key": "sql_pseudocode", "Type": "textarea", "Label": "SQL pseudocode or implementation notes", "HelpText": "Give SQL pseudocode showing joins, filters, windowing, and grouping. Example: 'SELECT DATE(event_time) as day, COUNT(DISTINCT order_id) / COUNT(DISTINCT session_id) as conversion_rate FROM events WHERE event_type IN (\'cart_add\', \'checkout_complete\') GROUP BY day;'. Include known parameters such as time_zone, event dedup rules, and primary keys.", "Required": false }, { "Key": "cardinality", "Type": "select", "Label": "Cardinality / primary grain", "HelpText": "Select the primary counting unit or grain of the metric. This clarifies whether it's per-user, per-session, per-order, per-device, etc.", "Required": true, "Options": [ { "Value": "per_event", "Label": "Per event" }, { "Value": "per_session", "Label": "Per session" }, { "Value": "per_user", "Label": "Per user" }, { "Value": "per_account", "Label": "Per account / customer" }, { "Value": "per_order", "Label": "Per order" }, { "Value": "other", "Label": "Other (explain below)" } ] }, { "Key": "cardinality_notes", "Type": "textarea", "Label": "Cardinality details / notes", "HelpText": "If 'Other' or extra explanation is needed, describe how unique keys are determined, de-duplication rules, and primary keys used.", "Required": false }, { "Key": "data_sources_lineage", "Type": "textarea", "Label": "Data sources & lineage", "HelpText": "List tables, events, systems, API endpoints, ETL jobs and transformations that produce the data used in this metric. Note any known upstream owners and refresh schedules.", "Required": true }, { "Key": "owner", "Type": "text", "Label": "Metric owner", "HelpText": "Person or role accountable for the metric (e.g., 'Product Analytics / Lead: Name, email'). This owner is responsible for accuracy, definition changes, and reviews.", "Required": true }, { "Key": "consumers", "Type": "textarea", "Label": "Primary consumers and downstream uses", "HelpText": "Who uses this metric (roles, teams, reports, dashboards, alerts)? How is it acted on? Example: 'Used in Weekly Ops dashboard and automated alert to SRE.'", "Required": false }, { "Key": "frequency", "Type": "select", "Label": "Calculation frequency", "HelpText": "How often is the metric computed or expected to be fresh? Choose the usual cadence for reporting and alerting.", "Required": true, "Options": [ { "Value": "real_time", "Label": "Real-time / streaming" }, { "Value": "hourly", "Label": "Hourly" }, { "Value": "daily", "Label": "Daily" }, { "Value": "weekly", "Label": "Weekly" }, { "Value": "monthly", "Label": "Monthly" }, { "Value": "quarterly", "Label": "Quarterly" } ] }, { "Key": "unit", "Type": "text", "Label": "Unit", "HelpText": "Unit of measure (e.g., %, count, seconds, $).", "Required": true }, { "Key": "tolerance_bands", "Type": "textarea", "Label": "SLA, target, and tolerance bands", "HelpText": "Define target, acceptable range, warning thresholds, and breach conditions. Example: 'Target=2.5% ±0.3%; Warning if <2.2%; Breach if <1.9% for two consecutive days.'", "Required": false }, { "Key": "known_limitations_transformations", "Type": "textarea", "Label": "Known limitations and approved transformations", "HelpText": "Document known data quality issues, sampling, imputation, smoothing, outlier treatment, or when the metric may be unreliable. Record approved transformations and who authorized them.", "Required": false }, { "Key": "monitoring_alerts", "Type": "textarea", "Label": "Monitoring, alerts and ownership for anomalies", "HelpText": "Describe any alerts, anomaly detection, responsible on-call, and runbooks or escalation steps tied to this metric.", "Required": false }, { "Key": "example_values_baseline", "Type": "textarea", "Label": "Example values and baseline", "HelpText": "Give representative examples (recent values, baseline, seasonality notes) so reviewers can sanity-check the metric when it's implemented.", "Required": false }, { "Key": "contains_pii", "Type": "yesno", "Label": "Contains PII or sensitive data?", "HelpText": "Select yes if the metric uses personally identifiable information or other regulated data. If yes, note compliance and retention constraints in the limitations field above.", "Required": false }, { "Key": "review_cycle", "Type": "select", "Label": "Review cycle", "HelpText": "How often should the owner review and reauthorize the metric definition?", "Required": true, "Options": [ { "Value": "monthly", "Label": "Monthly" }, { "Value": "quarterly", "Label": "Quarterly" }, { "Value": "annually", "Label": "Annually" }, { "Value": "ad_hoc", "Label": "Ad-hoc / as needed" } ] }, { "Key": "tags", "Type": "text", "Label": "Tags / categories", "HelpText": "Comma-separated tags to help cataloging (e.g., 'revenue, funnel, ops, sla').", "Required": false }, { "Key": "effective_date", "Type": "text", "Label": "Effective date / version notes", "HelpText": "When this definition takes effect and any short version history or version number.", "Required": false } ] }