Catalog Field Guide
Use this guide to understand what each OpenKPIs field means and what a complete, concise value should contain. The Add form remains intentionally short; editors and the automated workflow complete the full contract during review.
Contract version 5. These definitions are the shared source for the editor, validation, AI authoring, GitHub output, and public catalog.
Showing 45 fields.
| Field | Applies to | Business meaning | Expected value | Format and limits | Examples |
|---|---|---|---|---|---|
entity_type | KPI, Metric, Dimension, Event | Identifies the kind of catalog concept: KPI for a decision-oriented performance indicator, Metric for a reusable quantitative measure, Dimension for a descriptive breakdown attribute, or Event for one observable business occurrence. | One exact lowercase token. Use kpi only for a measure interpreted against an objective or outcome; metric for a reusable quantity without that performance framing; dimension for a categorical or descriptive value; event for a timestamped occurrence. | Format: enum Allowed: kpi; metric; dimension; event | Good: kpi Avoid: KPI record |
slug | KPI, Metric, Dimension, Event | Provides the stable URL and catalog identity for the concept. | A lowercase kebab-case identity normally derived from the prevailing name. | Format: lowercase-kebab-case Length: 3–120 characters | Good: abandoned-cart-recovery-rate Avoid: Abandoned Cart Recovery Rate KPI |
name | KPI, Metric, Dimension, Event | States the prevailing business or analytics term a general reader will recognize. | A concise noun phrase naming only the concept, without a definition or implementation detail. | Format: plain-text Length: 3–100 characters | Good: Abandoned Cart Recovery Rate Avoid: Advanced Seven-Day GA4 Cart Cohort Recovery KPI |
aliases | KPI, Metric, Dimension, Event | Lists established alternate names or abbreviations for the same concept. | Zero to eight equivalent names or abbreviations. Exclude dependencies, related concepts, platform tokens, invented variants, and the canonical name. | Format: semicolon-list | Good: ATC Rate; Add-to-Cart Rate Avoid: purchase; checkout; useful conversion measure |
description | KPI, Metric, Dimension, Event | Explains what the record means and why a business reader would use it. | One or two plain-language sentences defining the concept and its decision relevance, without formulas or implementation mechanics. | Format: one-or-two-sentences Length: 40–220 characters | Good: Percentage of abandoned carts that later result in a completed order. It shows how much abandoned shopping demand returns to purchase. Avoid: A sophisticated matured-cart cohort metric computed from identity-stitched event streams. |
formula | KPI, Metric, Dimension | Shows the shortest unambiguous arithmetic or transformation that produces the value. | A single readable expression using recognizable business quantities; move timing, exclusions, deduplication, and attribution rules to Calculation Notes. | Format: business-expression Length: 5–300 characters | Good: (Orders from previously abandoned carts / Total abandoned carts) × 100 Avoid: Recovered matured cohorts divided by eligible canonicalized cart entities after stitching. |
category | KPI, Metric, Dimension, Event | Classifies the concept by its primary measurement purpose. | Exactly one category selected by primary measurement purpose: Acquisition brings prospects or traffic; Engagement covers views, clicks, searches, or selections that do not complete a declared funnel objective; Conversion covers cart additions, checkout starts or completions, purchases, leads, sign-ups, and measures of progression to those outcomes; Revenue & Monetization covers fields and measures whose own meaning is a commercial amount, sales volume, units, price, refunded value, currency, average order value, or basket size; Retention covers continuation or return; Satisfaction is limited to direct perception, sentiment, effort, complaint, or recommendation measures; Operational Efficiency covers business-process throughput, timeliness, accuracy, capacity, and cost; Technical Reliability covers speed, availability, latency, errors, and system stability; Data Quality & Governance covers identity resolution, consent, data quality, controls, compliance, and stewardship; Other is allowed only when none applies. For KPI, Metric, and Event records, classify what the record measures or represents, not every analysis it could support or only its prerequisite Event. A purchase Event or a purchase-specific identifier is Conversion even when analysts can use it to group revenue; an amount, price, quantity, currency, or basket-size field is Revenue & Monetization. A count of confirmed orders is sales volume and remains Revenue & Monetization even when used for workload planning. A preference or method selection that does not complete a declared funnel objective is Engagement. For KPI, Metric, and Event records, use Operational Efficiency only for execution of an operational process, such as throughput time, cost, capacity use, accuracy, or fulfillment completion. For Dimensions, classify the primary analysis domain represented rather than treating the attribute as a measure; Fulfillment Channel and Inventory Availability Status are Operational Efficiency. Journey area, accountable function, industry, and criticality belong in their dedicated fields. | Format: enum Allowed: Acquisition; Engagement; Conversion; Revenue & Monetization; Retention; Satisfaction; Operational Efficiency; Technical Reliability; Data Quality & Governance; Other | Good: Conversion for Purchase Completed; Conversion for Purchase Product Identifier; Revenue & Monetization for Average Items per Order; Operational Efficiency for Order Fulfillment Time; Operational Efficiency for Fulfillment Channel; Technical Reliability for Page Load Time Avoid: Experience; Operations; Performance; Revenue and Conversion |
tags | KPI, Metric, Dimension, Event | Adds concise search terms that help readers discover the record. | Two to eight distinct domain, journey, or subject labels; avoid sentences and redundant variants. | Format: string-list | Good: cart recovery; checkout; conversion Avoid: This KPI is used by e-commerce teams to understand cart recovery |
industry | KPI, Metric, Dimension, Event | Identifies every industry where the definition genuinely applies without modification. | One or more exact site industries based on real applicability, not the automation's temporary portfolio focus. | Format: enum-list Allowed: Retail; E-commerce; SaaS; Healthcare; Education; Finance; Media; Technology; Manufacturing; Travel & Hospitality; Telecommunications; Automotive; Other | Good: E-commerce; Retail; Telecommunications Avoid: E-commerce only because the current automation batch focuses there |
business_criticality | KPI, Metric, Dimension, Event | Expresses the materiality of missing or incorrect measurement to business decisions. | Critical for regulatory, financial, customer-risk, or core-operational harm; High for routine material decisions; Medium for optimization; Low for diagnostic or specialized support. This describes decision risk, not whether the current result is good or bad. | Format: enum Allowed: Critical; High; Medium; Low | Good: High Avoid: Critical because this month's result declined |
core_area | KPI, Metric, Dimension, Event | Identifies one to three journey or navigation areas where the concept occurs. | Select the smallest set of one to three journey areas needed for discovery. Use Cross-Journey only when the concept genuinely spans stages and no smaller set is clearer. This is not the owning function, Category, Industry, or an analytics discipline. | Format: enum-list Allowed: Acquisition; Discovery; Consideration; Product Experience; Cart; Checkout; Payment; Purchase; Post-Purchase; Fulfillment; Returns & Refunds; Loyalty & Retention; Customer Service; Account & Identity; Store Experience; Cross-Journey | Good: Cart; Checkout; Store Experience; Purchase Avoid: Store Operations; Digital Analytics |
owner | KPI, Metric, Dimension, Event | Identifies the operating function accountable for the definition, quality, and interpretation. | Exactly one accountable operating function. Do not use a person, contributor, platform, journey area, or analytics discipline. | Format: enum Allowed: Marketing; Merchandising; Product Management; Digital Experience; Customer Experience; Customer Support; Store Operations; E-commerce Operations; Order Management; Fulfillment & Logistics; Inventory; Payments; Returns; Loyalty & CRM; Finance; Risk & Compliance; Data & Technology; People Operations | Good: E-commerce Operations Avoid: Jane Doe; Checkout; GA4 team |
scope | KPI, Metric, Dimension, Event | Identifies the closest standard measurement level at which the value is associated or the event is captured. | Choose exactly one: User for values associated with a person across interactions; Session for one visit or session; Event for a specific action or transaction occurrence, including purchases, orders, payments, shipments, and returns; Product for a product or item. Keep more specific business grain in the definition, formula, dependencies, parameters, and SQL. Do not create separate scope values for business objects such as Cart, Order, Purchase, Store, or Campaign. | Format: enum Allowed: User; Session; Event; Product | Good: User; Session; Event; Product Avoid: Purchase; Order; Cart; Global |
measurement_channels | KPI, Metric, Dimension, Event | Identifies the environments where the behavior or business fact occurs and is observed. | One or more exact channels. Select where the measured action occurs, not the acquisition source or the dashboard location. | Format: enum-list Allowed: Web; Mobile App; Backend / API; Store / POS; Marketing Messaging; Call Center / Support; External Platform / Partner; Connected Device / IoT; Other Offline | Good: Web; Mobile App; Store / POS Avoid: Paid Search; Executive Dashboard |
source_data | KPI, Metric, Dimension, Event | Lists the source-system families that supply the required facts without turning the field into architecture prose. | One to five exact vendor-neutral source families. Include Offline Operational System when collection is operational rather than browser-based, together with the specific source such as Point of Sale or Inventory or Warehouse. Digital Analytics plus Offline Operational System means hybrid collection. | Format: enum-list Allowed: Digital Analytics; Commerce Platform; Order Management; Product Information; Point of Sale; Inventory or Warehouse; CRM or CDP; Marketing Platform; Customer Support; Payment Processor; Finance or ERP; Experimentation Platform; Survey or Voice of Customer; Application or Server Logs; Offline Operational System; External Partner Data Length: 2–160 characters | Good: Digital Analytics; Commerce Platform; Order Management; Point of Sale; Order Management; Offline Operational System Avoid: Best-in-class omnichannel enterprise data platform that combines every customer source |
dependencies | KPI, Metric, Dimension, Event | Links the existing catalog records that are required to calculate or implement this record. | A JSON object with only Events, Metrics, Dimensions, and KPIs arrays. Include only direct inputs required to calculate or implement the record, and only as published existing catalog slugs. Exclude topical relationships, self-references, cycles, unused inputs, descriptions, and setup instructions. | Format: typed-slug-map | Good: {"Events":["add-to-cart","purchase"],"Metrics":[],"Dimensions":[],"KPIs":[]} Avoid: Needs GA4 configured correctly and a useful dashboard |
report_attributes | KPI, Metric, Dimension, Event | Lists valid dimensions readers can use to filter, group, or compare the value. | One to eight business attributes that are actually available from declared Event parameters, dependency Dimensions, or SQL fields. Use one concise attribute per line; do not invent desirable breakdowns. | Format: line-list | Good: Device category
Market
Customer type Avoid: Revenue, conversion rate, and every useful field |
dashboard_usage | KPI, Metric | Recommends a small set of reporting views where the measure would help a business user make a decision. | Zero to three short, generic reporting-view names separated by semicolons. Each name is 2–6 words and at most 60 characters. Derive them from the business use case, owning function, category, and available report attributes. They are recommendations and must not imply that a named dashboard is deployed. | Format: semicolon-list | Good: Checkout Funnel; Cart Recovery; Lifecycle Marketing Avoid: Executive Dashboard; Acme Global Commerce Command Center |
segment_eligibility | KPI, Metric, Dimension, Event | Defines the business-readable condition under which a record qualifies for a segment or audience. | One complete audience or population condition grounded in fields declared by this record or its dependencies. Use business field names with ALL-CAPS EXISTS, NOT EXISTS, EQUALS, NOT EQUALS, IN, NOT IN, CONTAINS, NOT CONTAINS, STARTS WITH, ENDS WITH, GREATER THAN, GREATER THAN OR EQUALS, LESS THAN, LESS THAN OR EQUALS, or BETWEEN; combine clauses only with ALL-CAPS AND/OR and parentheses. Quote string and list values; leave numbers unquoted. Do not put reporting-period filters, configured placeholders, SQL, Yes/No, examples, or commentary in this field. If segmentation is genuinely meaningless, use 'NOT APPLICABLE —' followed by one short reason. | Format: business-condition-expression Length: 8–220 characters | Good: Cart Status EQUALS "Abandoned" AND Cart Value GREATER THAN 0; Purchase Product Identifier EXISTS; Fulfillment Channel EQUALS "Store pickup" Avoid: true; Yes — this can be segmented; Checkout Start Date IN Selected Reporting Period; Location ID EQUALS Configured Report Location ID; Fulfillment Channel EQUALS "Store pickup" (illustrative example) |
data_sensitivity | KPI, Metric, Dimension, Event | Sets the handling level required by the most sensitive input or output. | Public only when both inputs and output can be openly shared; Internal for non-public business data or pseudonymous operational/analytics data with ordinary access controls; Restricted for direct personal identifiers, sensitive personal data, payment or authentication data, regulated data, or fine-grained records requiring tightly limited access. Use the highest level required by any input, mapping, query, or output. | Format: enum Allowed: Public; Internal; Restricted | Good: Internal Avoid: Restricted because all analytics data is private |
pii_flag | KPI, Metric, Dimension, Event | Indicates whether the implementation collects or processes personally identifiable information. | True when any input, mapping, or query contains a direct identifier or a persistent customer, shopper, account, user, or device identifier that can reasonably be linked to a person. False for anonymous event IDs, order IDs, cart IDs, product IDs, or aggregate outputs that cannot be linked to a person. Do not place raw email, phone, or other direct contact data in analytics payloads. | Format: boolean | Good: false when only anonymous cart and transaction identifiers are used Avoid: true because every analytics identifier is automatically PII |
aggregation_window | KPI, Metric, Dimension | Lists supported reporting windows for KPI/Metric records and optional lookback windows for Dimensions. | KPI/Metric: select reporting windows that preserve the definition. Dimension: select a lookback only when prior behavior determines the value. Fixed durations are allowed only when integral to the named definition; never invent a universal default. | Format: enum-list Allowed: Event; Session; User; Selected Reporting Period; Hourly; Daily; Weekly; Monthly; Quarterly; Yearly; Rolling 7 Days; Rolling 30 Days; Rolling 90 Days; Configured Lookback | Good: Daily; Weekly; Monthly Avoid: Every option because the dashboard can change dates |
measure_type | KPI, Metric | Classifies the mathematical form of the reported value. | Counter for a count of occurrences or entities; Sum for additive non-currency numeric values; Currency for additive monetary values; Average for an arithmetic mean; Ratio for one quantity divided by another without percent scaling; Percentage for a part-to-whole or conversion expression multiplied by 100; Rate for occurrences per unit of time or exposure. Select exactly one based on the formula and displayed unit. | Format: enum Allowed: Counter; Rate; Ratio; Percentage; Average; Sum; Currency | Good: Percentage Avoid: Rate for a formula multiplied by 100 and displayed as a percent |
data_type | Dimension | Declares the stored or exposed value type of the dimension. | string for text, codes, identifiers, or categories; number for numeric values; boolean only for true/false values; date for a calendar date; datetime for an instant with date and time; list for a repeated set of values. JSON is not a Dimension data type. | Format: enum Allowed: string; number; boolean; date; datetime; list | Good: string Avoid: JSON; counter; number when the values are labels such as mobile and desktop |
ga4_event_type | Event | Classifies the represented Event against the GA4 event taxonomy. | Choose Automatically Collected, Enhanced Measurement, Recommended, Custom, or Not Applicable using the dated official-source event registry. | Format: enum Allowed: Automatically Collected; Enhanced Measurement; Recommended; Custom; Not Applicable | Good: Recommended Avoid: Standard; Adobe Standard XDM |
adobe_event_type | Event | Classifies the represented Event against the Adobe XDM eventType taxonomy. | Choose Standard XDM, Custom XDM, or Not Applicable using the dated official-source Adobe registry. | Format: enum Allowed: Standard XDM; Custom XDM; Not Applicable | Good: Standard XDM Avoid: event12; GA4 Recommended |
event_serialization | Event | Defines exactly when one event instance is emitted and how duplicates are prevented. | One concise firing and deduplication rule, including the stable event key when applicable. | Format: single-rule Length: 3–120 characters | Good: Fire once after order confirmation; deduplicate by transaction_id. Avoid: JSON event serialization format |
trigger_condition | Event | States the completed business state transition that emits the Event. | One concise condition in WHEN …, THEN emit … form. Use the completed action or state change, not a click that merely precedes it. | Format: single-condition Length: 12–180 characters | Good: WHEN an order is confirmed, THEN emit purchase_completed. Avoid: When the button is clicked |
ga4_event | KPI, Metric, Dimension, Event | Lists the GA4 events required to create the record's data. | For digital or hybrid derived records, one lower_snake_case event and short purpose per line using 'event_name — purpose'. Leave empty for explicitly offline records. | Format: event-inventory Length: 0–800 characters | Good: add_to_cart — establishes cart contents
purchase — confirms the completed order Avoid: Collect purchase and configure tags, mappings, identifiers, dimensions, and reporting rules. |
adobe_event | KPI, Metric, Dimension, Event | Lists the Adobe collection events or actions required to create the record's data. | For digital or hybrid derived records, one event/action token and short purpose per line using 'event_name — purpose'. Leave empty for explicitly offline records. | Format: event-inventory Length: 0–800 characters | Good: cart_add — establishes cart contents
purchase — confirms the completed order Avoid: Map additions and purchases, configure rules, populate XDM, and replace the tenant namespace. |
parameters | Event | Defines the compact canonical parameter contract for one atomic Event and links every parameter to all four mapping fields. | For a digital or hybrid Event, use a JSON object with no more than twenty lower_snake_case keys; each value contains type, required, a meaning of at most 80 characters, and dot-notation paths for w3, ga4, adobe, and xdm. Resolve standard parameters and paths from the dated local data-contract RAG. A custom parameter also contains unique purposes selected from event_identity, deduplication, calculation, segmentation, breakdown, attribution, and privacy_control, plus a 12–120 character justification of why the Event cannot be implemented without it. A numeric .0 segment represents the element schema of a repeatable array, not a single-item limit. A scalar cross-platform total may map to repeated line values only when the contract explicitly requires summing every line with the same amount basis. For purchase/refund merchandise value, GA4 ecommerce.value excludes tax and shipping and aligns to the sum of Adobe/XDM productListItems priceTotal or refundAmount; it does not align to tax-inclusive commerce.order.priceTotal. For an explicitly offline Event, each operational parameter contains only type, required, and meaning but no browser mapping paths. Every mapped or queried business field must be declared, and extra undeclared fields are not allowed. When an authoritative Event parameter contract is supplied, copy its complete metadata exactly instead of paraphrasing or expanding it. | Format: json-cross-platform-parameter-map | Good: {"transaction_id":{"type":"string","required":true,"meaning":"Unique confirmed order identifier","paths":{"w3":"digitalData.transaction.transactionID","ga4":"ecommerce.transaction_id","adobe":"eventInfo.transactionId","xdm":"commerce.order.purchaseID"}},"cart_id":{"type":"string","required":true,"meaning":"Cart connected to the event","purposes":["event_identity","calculation"],"justification":"Connects cart activity to the resulting order.","paths":{"w3":"digitalData.cart.cartID","ga4":"cart_id","adobe":"data.cart_id","xdm":"commerce.cart.cartID"}}} Avoid: transaction_id, value, currency and other useful parameters |
w3_data_layer | KPI, Metric, Dimension, Event | Shows the canonical business-event payloads from which the platform-specific mappings are derived. | For digital or hybrid records, valid CEDDL JSON rooted at digitalData. digitalData.event is an array with one eventInfo object per canonical Event dependency, plus only required shared business objects and identifiers. Use standard CEDDL paths or the documented attributes extension points from the local data-contract RAG; never invent a new digitalData root or standard-looking path. eventInfo.eventName uses the neutral lower_snake_case catalog Event slug, such as cart_item_added; it does not copy a platform-specific GA4 token such as add_to_cart unless both names are identical. A representative array element demonstrates a repeatable schema rather than limiting cardinality. Leave empty for explicitly offline records. | Format: ceddl-json | Good: {"digitalData":{"event":[{"eventInfo":{"eventName":"purchase_completed"}}]}} Avoid: window.digitalData = {...} or a purchase-only fragment when several lifecycle events are required |
ga4_data_layer | KPI, Metric, Dimension, Event | Shows the exact GA4 dataLayer payloads needed to produce every listed GA4 event. | For digital or hybrid records, a JSON array with exactly one representative root-event payload for every GA4 Event inventory item, including Event records. Include every required and conditionally required parameter documented for that Event in the local data-contract RAG. Each ecommerce item contains item_id or item_name. Use only documented ecommerce and item fields; custom parameters are root siblings of ecommerce and must be justified in parameters. Include every parameter referenced by GA4 SQL. One representative item demonstrates the repeatable items schema and does not limit a transaction to one item. Leave empty for explicitly offline records. | Format: ga4-payload-set | Good: [{"event":"add_to_cart","ecommerce":{"items":[]}},{"event":"purchase","ecommerce":{"transaction_id":"T-123","items":[]}}] Avoid: A purchase-only payload when add_to_cart and begin_checkout are also listed |
adobe_client_data_layer | KPI, Metric, Dimension, Event | Shows the Adobe Client Data Layer pushes needed for every listed Adobe event. | For digital or hybrid records, a JSON array containing exactly one representative pushed event object for every Adobe Event inventory item, with only fields mapped into XDM or used by AEP SQL. Keep business fields in the documented data or eventInfo envelope, or in an explicitly approved XDM-shaped envelope from the local data-contract RAG; do not invent arbitrary message-root fields. Use productListItems for repeatable commerce lines; a .0 path defines its element schema. Leave empty for explicitly offline records. | Format: adobe-payload-set | Good: [{"event":"cart_add","eventInfo":{"cartId":"C-123"}},{"event":"purchase","eventInfo":{"transactionId":"T-123"}}] Avoid: One purchase object when the Adobe event inventory also names cart_add |
xdm_mapping | KPI, Metric, Dimension, Event | Maps every Adobe event payload into an equivalent ExperienceEvent shape used by AEP Query Service. | For digital or hybrid records, a JSON array with exactly one ExperienceEvent object per Adobe Event inventory item. Each object has _id, timestamp, eventType, and paths whose type is grounded by the local XDM profile or an explicitly configured tenant namespace. An absent standard path is a hold-and-research condition, not permission to invent one. identityMap is used only when identity is needed. productListItems is repeatable even when one representative item is shown. Leave empty for explicitly offline records. | Format: xdm-payload-set | Good: [{"_id":"purchase-T-123","timestamp":"2026-10-16T12:00:00Z","eventType":"commerce.purchases","commerce":{"purchases":{"value":1}}}] Avoid: Deprecated endUserIDs or invented _experience.analytics.custom1 paths |
ga4_sql | KPI, Metric, Dimension | Implements the published definition against the documented GA4 BigQuery export schema. | For digital or hybrid KPI, Metric, and Dimension records, one read-only query generated only after the Event and parameter crosswalk is approved. Use every and only declared GA4 events and the smallest parameter subset required by this record's formula, filters, grouping, identity, or deduplication; every parameter must map to a dependency Event. Translate collection paths to the documented export: value, currency, and custom keys come from event_params; item keys come from items; never query collection-only ecommerce.value, ecommerce.currency, or ecommerce.items. Read only the documented GA4 events_* export and preserve the definition's grain, formula, filters, window, units, deduplication, and zero-denominator behavior. Correlate multi-event progressions with the exact shared declared identifier and require the outcome after the start. A descriptive Dimension returns the collected value unchanged unless its definition explicitly requires a transformation. Apply the exclusive report-end bound before deduplication or conflict checks so later data cannot change history. Do not invent duplicate-conflict policies; keep unspecified source uniqueness or conflict handling as integration prerequisites. Treat _TABLE_SUFFIX as coarse pruning in the GA4 property reporting timezone; when exact bounds are UTC and the property timezone is not fixed, include a one-day boundary buffer and enforce the interval with event_timestamp. Prefer 25 or fewer executable lines; a simple one-event sum or descriptive Dimension uses a direct query or at most 30 lines/1 CTE/1 join, ordinary multi-event queries 50 lines/3 CTEs, and explicitly justified sequence, identity, deduplication, refund, attribution, or window logic 80 lines/5 CTEs. Never use SELECT *. Leave empty for Event and explicitly offline records. | Format: read-only-sql | Good: SELECT SAFE_DIVIDE(COUNTIF(event_name='purchase'), COUNTIF(event_name='begin_checkout')) * 100 FROM `project.analytics.events_*` Avoid: SELECT * plus debug outputs, unrelated joins, or events not declared above |
aep_sql | KPI, Metric, Dimension | Implements the same published definition for the selected AEP dataset profile. | For digital or hybrid KPI, Metric, and Dimension records, one read-only AEP Query Service query generated from the same approved Event and item-specific parameter subset as GA4 SQL. Use every and only declared Adobe events; every selected XDM path must map to a dependency Event and exist in the declared AEP dataset profile. Select one canonical identity from the configured identityMap namespace per event; never explode aliases into extra shoppers or other business entities. Apply the same exact progression correlation, unchanged descriptive-Dimension projection, exclusive report-end boundary, and no-invented-conflict-policy rules as GA4 SQL. Preserve the same grain, formula, filters, window, units, deduplication, and zero-denominator behavior as GA4 SQL. Apply the same preferred 25-line and maximum 30/50/80-line complexity tiers. Leave empty for Event and explicitly offline records. | Format: read-only-sql | Good: SELECT SUM(commerce.purchases.value) FROM {{AEP_EXPERIENCE_EVENT_DATASET}} WHERE eventType='commerce.purchases' Avoid: A query using an assumed universal table or different business rules from GA4 |
calculation_notes | KPI, Metric, Dimension, Event | Records only the rules needed to calculate or interpret the value consistently. | One to five emoji-numbered bullets covering only necessary timing, inclusion, exclusion, deduplication, attribution, or zero-denominator rules; one rule per bullet. Do not add filler to reach a count. | Format: emoji-numbered-bullets | Good: 1️⃣ Count each confirmed order once. 2️⃣ Use the configured recovery period. 3️⃣ Return null when no carts qualify. Avoid: A seven-bullet technical design containing implementation history, schema caveats, and review commentary |
business_use_case | KPI, Metric, Dimension, Event | Explains who uses the record, what signal prompts attention, and what decision follows. | One to three emoji-numbered bullets; each contains an actor and a concrete decision or action. Do not repeat the description or add generic filler. | Format: emoji-numbered-bullets | Good: 1️⃣ Checkout teams investigate a sustained decline. 2️⃣ CRM teams compare recovery methods before changing outreach. Avoid: Track the KPI because it is important and useful for the business |
related_kpis | KPI | Links existing KPIs that help readers compare or interpret this KPI. | Zero to eight existing KPI slugs; exclude required inputs and duplicate concepts. | Format: semicolon-slug-list | Good: cart-abandonment-rate;cart-to-purchase-rate Avoid: purchase;order_id;new recovery KPI to create later |
related_metrics | Metric | Links existing Metrics that help readers compare or interpret this Metric. | Zero to eight existing Metric slugs; exclude required inputs and duplicate concepts. | Format: semicolon-slug-list | Good: orders;abandoned-carts Avoid: Useful conversion metrics and related information |
related_dimensions | Dimension, Event | Links existing Dimensions that provide adjacent context but are not derived from this record. | Zero to eight existing Dimension slugs with no circular or speculative references. | Format: semicolon-slug-list | Good: device-category;customer-type Avoid: Any dimension that might be useful in a future report |
derived_kpis | Metric, Event | Links existing KPIs whose calculation directly uses this Metric or Event. | Existing KPI slugs with demonstrable direct lineage, not merely topical similarity. | Format: semicolon-slug-list | Good: checkout-completion-rate Avoid: All conversion KPIs |
derived_metrics | Event | Links existing Metrics whose calculation directly uses this Event. | Existing Metric slugs with demonstrable direct lineage. | Format: semicolon-slug-list | Good: orders Avoid: Potential future purchase reporting |
derived_dimensions | Dimension, Event | Links existing Dimensions directly transformed or extracted from this record. | Existing Dimension slugs with explicit transformation or extraction lineage. | Format: semicolon-slug-list | Good: purchase-value-band Avoid: device-category when it is collected independently |