Section 5 · OES Spec
Metric definitions
Snapshot metric identity AND calculation — definitions change.
A portable standard must distinguish metric identity from metric calculation. Two systems can both have a metric called 'Revenue'; unless the numerator, denominator, attribution window, and filters are captured, the result is not portable. OES requires that metric definitions be snapshotted into the document at the time of analysis, not merely referenced by ID.
Fields
| Field | Type | Purpose |
|---|---|---|
| metric.idrequired | string | Stable metric ID. |
| metric.namerequired | string | Human name. |
| metric.description | string | Plain-English definition. |
| metric.role | enum | primary, secondary, guardrail, diagnostic, data_quality, invariant. |
| metric.direction | enum | increase_is_good, decrease_is_good, no_change_expected, two_sided. |
| metric.type | enum | conversion, revenue, count, duration, ratio, retention, percentile, custom. |
| metric.unit | string | users, dollars, sessions, milliseconds, events/user, etc. |
| metric.numerator | object | Definition or query for the numerator. |
| metric.denominator | object | Definition or query for the denominator. |
| metric.aggregation | enum | mean, sum, ratio, percentile, capped_mean, winsorized_mean. |
| metric.analysisWindow | object | Conversion, attribution, or retention window. |
| metric.dataSource | object | Warehouse, table, or event source. |
| metric.sql | string | Optional SQL definition. |
| metric.filters | object[] | Metric-level filters. |
| metric.capping | object | Outlier capping or winsorization rules. |
| metric.covariates | object[] | CUPED or pre-period covariates, if used. |
| metric.owner | object | Metric owner or team. |