Metrics

1. Overview

This module defines a minimal shared vocabulary for metric observations that can be exchanged between UJG producers, stores, and consumers. The first standardized slice is Mapping-derived metrics: counts and rates computed from Runtime event chains after they have been resolved against Graph intent by Mapping.

Metrics intentionally describe observed facts, not product-specific interpretations. For example, an unexplained movement records that Mapping could not identify a relevant effective transition for the movement. It does not imply that the movement was erroneous, invalid, or undesirable.

This draft does not standardize conversion goals, drop-off semantics, dwell-time metrics, histograms, sketches, or event taxonomies. Those can be defined by profiles or future modules.

2. Terminology

• MetricObservation: An addressable observation that attaches one metric value to one metric subject.

• Metric subject: The UJG object that a metric describes, identified by metricSubjectRef.

• Metric key: The portable name of the measured fact, identified by metricKey.

• Count metric: A non-negative integer metric that counts occurrences.

• Rate metric: A decimal metric in the closed interval 0..1, computed from an explicit numerator and denominator.

• Mapping-derived metric: A metric computed from one or more JourneyMapping records and their MappedStep records.

• Source mapping: The JourneyMapping used to compute a single-execution metric, identified by sourceMappingRef when applicable.

3. Metric Model

A MetricObservation records a metric value using these fields:

• metricSubjectRef: the UJG object that the metric describes.

• metricKey: the metric name.

• metricValue: the metric value.

• metricUnit: the unit of metricValue.

• numeratorCount: the numerator used to compute a rate metric, when applicable.

• denominatorCount: the denominator used to compute a rate metric, when applicable.

• aggregationMethod: the method used to combine or derive an aggregate metric, when applicable.

• sourceMappingRef: the JourneyMapping used to compute the metric, when the metric is derived from a single mapping.

4. Mapping-derived Metrics

Mapping is the canonical interpretation layer for analytics over UJG execution data. Runtime records what happened, Graph defines the intended journey topology, and Mapping resolves each Runtime event to Graph state and transition intent.

Mapping-derived metrics use these primary attachment points:

For Mapping-derived metrics, the Runtime event chain defines order. The serialized order of mappedStepRef is not significant.

5. Core Metric Keys

The following metric keys are core for this draft.

These keys use unexplainedMovement* terminology rather than jump*, error*, or conversion*. Mapping can derive a jump when no relevant effective transition explains a movement, but Metrics does not classify that movement as an error.

6. Units and Value Conventions

Runtime ordering is causal, not timestamp-based. This draft defines duration value conventions but does not define dwell-time or elapsed-time metric keys as core metrics.

7. Aggregation

Metrics may be computed from one JourneyMapping or aggregated over disjoint sets of mappings. Aggregates must preserve the meaning of the underlying metric key.

8. Extension Metric Keys

Profiles and implementations may define additional metric keys for product-specific analytics, domain-specific event taxonomies, or richer statistical summaries.

Extension metric keys SHOULD be namespaced so they do not collide with core metric keys. An extension metric definition SHOULD specify:

• the metric subject type;

• the unit and value type;

• the calculation rule;

• aggregation behavior;

• whether the metric is computed from Mapping, Runtime, Graph, or external data.

The following metrics are intentionally profile-defined in this draft:

9. Validation

This draft describes the Metrics model but does not yet publish Metrics ontology, JSON-LD context, or SHACL artifacts. Producers and consumers can still validate the baseline model by checking that:

• every metric observation has one subject, one key, and one value;

• count values are non-negative integers;

• rate values are in the closed interval 0..1;

• rate observations include or can derive their numerator and denominator;

• Mapping-derived movement rates use movementCount as the denominator;

• undefined rates are omitted rather than serialized as 0.

10. Examples

{
  "@id": "urn:ujg:metric:checkout:unexplained-rate",
  "@type": "MetricObservation",
  "metricSubjectRef": "urn:ujg:mapping:execution-12345",
  "metricKey": "unexplainedMovementRate",
  "metricValue": 0.25,
  "metricUnit": "ratio",
  "numeratorCount": 1,
  "denominatorCount": 4,
  "sourceMappingRef": "urn:ujg:mapping:execution-12345"
}

{
  "@id": "urn:ujg:metric:checkout:unexplained-rate",
  "@type": "MetricObservation",
  "metricSubjectRef": "urn:ujg:mapping:execution-12345",
  "metricKey": "unexplainedMovementRate",
  "metricValue": 0.25,
  "metricUnit": "ratio",
  "numeratorCount": 1,
  "denominatorCount": 4,
  "sourceMappingRef": "urn:ujg:mapping:execution-12345"
}

{
  "@id": "urn:ujg:metric:checkout:transition-cart-payment",
  "@type": "MetricObservation",
  "metricSubjectRef": "urn:ujg:transition:cart-to-payment",
  "metricKey": "transitionTraversalCount",
  "metricValue": 812,
  "metricUnit": "count",
  "aggregationMethod": "sum"
}

{
  "@id": "urn:ujg:metric:checkout:transition-cart-payment",
  "@type": "MetricObservation",
  "metricSubjectRef": "urn:ujg:transition:cart-to-payment",
  "metricKey": "transitionTraversalCount",
  "metricValue": 812,
  "metricUnit": "count",
  "aggregationMethod": "sum"
}