Learning/Product Analytics Event Taxonomy

Three products say “lesson complete.” Do they mean the same event?

One MAKNOW surface emits lesson_done, another emits completedLesson, and a third creates lesson-complete-42, embedding the lesson identifier in the event name. One producer records device time, another records server receipt time, and the dashboard treats every “complete” event as proof of mastery.

That pipeline can produce charts, but it does not yet produce trustworthy analytics. A raw occurrence is evidence that something happened according to a producer; it is not automatically proof of learner intent, mastery, causal impact, or even semantic equivalence across versions.

In this lesson you build Learning & Product Event Taxonomy Governance Contract v1. It separates stable event semantics from instance data, distinguishes event time from observed time, binds each record to taxonomy/schema/producer versions, classifies privacy and cardinality, governs deprecation/migration, and keeps derived metrics and mastery claims downstream of raw event evidence.

Core rule: stable event meaning first; occurrence evidence second; interpretation only under a separate evidence contract.

For: learning-platform engineers, analytics engineers, product/data teams, instrumentation owners, and governance reviewers. Not for: collecting real learner telemetry in this lesson, rewriting historical meaning, inferring mastery from a click, or treating Caliper/OpenTelemetry as permission to define MAKNOW product policy.

Route orientation and ownership boundary

MKN-020 owns only Learning/Product Analytics Event Taxonomy. Its frozen prerequisites are MKN-017 (hard) and MKN-019 (soft). MKN-019 owns Matching, Fairness & Explainability; MKN-021 owns Contributor and Editorial Governance. This lesson does not absorb either outcome.

Foundation learners use a field map and one worked canonicalization case. Repair learners isolate the first semantic or provenance defect and rerun the affected gate. Experienced learners defend migration, versioning, replay, privacy, and derived-metric boundaries without hiding them inside a single “analytics quality” score.

Checkpoints: F1 state the owned boundary and one non-goal; F2 diagnose a dynamic event name and a mastery-overclaim; F3 recompute the taxonomy result for an offline mobile producer that uploads after a taxonomy revision.

Mental model: semantic contract → occurrence record → validation → storage → derivation

Use this ordered flow:

taxonomy version → stable event definition → producer/schema version → event occurrence → event time + observed time → validation/privacy/cardinality → immutable raw record → migration/deprecation view → derived metric → separately justified learning claim

The event taxonomy answers what this event means, not whether a learner mastered a concept. Instance attributes answer which occurrence happened. The producer version answers which instrumentation emitted it. Event time answers when the occurrence happened; observed time answers when a collector or later component saw it. These timestamps may diverge without either being “wrong.”

Typed states matter. A candidate can be REVIEW_REQUIRED, HOLD_DYNAMIC_EVENT_NAME, HOLD_TIMESTAMP_EVIDENCE, HOLD_MIGRATION_MISSING, HOLD_MASTERY_INFERENCE, HOLD_PRIVACY_CLASS, or another explicit non-success state. The system should say why it cannot promote a taxonomy entry instead of coercing uncertainty into “valid=true.”

Foundation contract: every event needs stable semantics and replayable provenance

The frozen critical dimensions are: taxonomy_version, event_name, event_definition, actor_ref_pseudonymous, object_ref, action_or_state, event_timestamp, observed_timestamp, context_ref, outcome, attribute_semantics, cardinality_class, privacy_class, schema_version, producer_version, validation_state, deprecation_state, replacement_event, derived_metric_ref, mastery_claim_forbidden_without_evidence, and provenance.

Minimum invariants:

1. Event names are stable semantic identifiers. Put lesson IDs, user IDs, attempt numbers, resource IDs, and other dynamic values in attributes, not in the event name.
2. Definition precedes emission. The taxonomy states the occurrence represented by the event and the allowed/required attributes.
3. Actor references are pseudonymous where the contract requires it. Privacy classification is explicit; it is not inferred from field spelling.
4. Event time and observed time are different fields. Delayed/offline upload can legitimately produce a later observed timestamp.
5. Taxonomy, schema, and producer versions are distinct. Changing instrumentation does not silently change event meaning; changing meaning requires governed version/migration treatment.
6. Validation is explicit. Missing decisive fields produce HOLD/UNKNOWN/REVIEW_REQUIRED rather than a “best effort” positive record.
7. Deprecation does not erase history. Deprecated events retain their original meaning, with a replacement/migration reference where applicable.
8. Derived metrics are downstream. A count, funnel, retention metric, or learning indicator names its derivation; it does not overwrite the raw event.
9. A raw event does not prove mastery. Mastery requires a separate evidence contract and interpretation rule.
10. Replay is semantics-preserving. Historical records may be transformed for compatibility only with explicit migration provenance; the original meaning/version remains recoverable.

Deep explanation: interoperability vocabulary is not local interpretation authority

1EdTech Caliper. The current 1EdTech Caliper page still describes a common language and metric profiles for representing learning activities across instructional technologies, and identifies Caliper Analytics 1.2 as the current specification resource. That is useful when a MAKNOW learning interaction maps cleanly to a Caliper profile. It does not define MAKNOW mastery thresholds, product KPI formulas, retention policy, or privacy policy.

OpenTelemetry event semantic conventions. The current event semantic-convention page describes events as named occurrences at a meaningful point in time. It requires a meaningful event name, says event names must not include dynamic values, requires the timestamp to represent when the event occurred, and keeps observed/received time conceptually separate. Its page is currently marked Development, so MAKNOW treats it as evolving practice rather than frozen local authority.

MAKNOW inference. Together, these sources support a strong engineering inference: stable names plus structured attributes and versioned producer semantics make cross-product analysis more comparable than ad-hoc dynamic names. They also support separating occurrence time from receipt/observation time. They do not establish that “completion” means mastery.

MAKNOW design authority. Event namespace, required fields, privacy classes, cardinality policy, validation states, deprecation windows, migration rules, replay policy, metric definitions, retention, and learning-claim interpretation remain local governance decisions. External specifications inform representation; they do not grant permission to reinterpret learner evidence.

Worked examples

Example A — canonicalize three legacy completion events

Legacy producers emit lesson_done, completedLesson, and lesson-complete-42. The third name is structurally defective because the identifier 42 is embedded in the event name. The governance contract defines a stable canonical event such as learning.lesson.completed, places the lesson identifier in object_ref, records the producer version, and maps legacy names through explicit migration evidence.

The raw outcome is an occurrence like “producer reported lesson completion according to taxonomy v3.” It is not “learner mastered lesson 42.” mastery_claim_forbidden_without_evidence=true remains visible.

Correct ceiling: TAXONOMY_REVIEW_REQUIRED. A human/governed promotion step remains accountable for accepting the taxonomy mapping.

Example B — offline mobile event arrives two days later

The mobile client records event_timestamp=2026-09-10T09:00Z, goes offline, and the collector receives the record on observed_timestamp=2026-09-12T14:00Z. This is not automatically a timestamp error. The contract preserves both times, the producer version, the old taxonomy/schema identity, and migration provenance.

If the new taxonomy renames the event, do not overwrite the stored old name and pretend the producer emitted the new meaning. Keep the historical record and add a governed compatibility/migration view.

Example C — click event feeds a “mastery rate” dashboard

A learner clicks Complete. The raw event validates. The dashboard then labels the learner “mastered” with no assessment, rubric, or separate learning evidence.

Correct result: HOLD_MASTERY_INFERENCE for that interpretation path. The occurrence can remain valid while the mastery claim is invalid. This distinction is the core semantic boundary of the lesson.

Failure modes and adversarial probes

• Dynamic event name: lesson-complete-42 creates unbounded names and hides the object identifier inside taxonomy identity. → HOLD_DYNAMIC_EVENT_NAME.
• Definition drift without versioning: the same name begins to mean “opened lesson” in producer v8. → HOLD_SCHEMA_OR_MEANING_DRIFT.
• Observed time replaces event time: delayed mobile upload is reported as if the action happened at receipt. → HOLD_TIMESTAMP_EVIDENCE.
• Rename without migration map: a new producer silently rewrites old records to a new canonical name. → HOLD_MIGRATION_MISSING.
• Missing producer/schema version: analysts cannot reproduce which contract emitted the record. → HOLD_VERSION_EVIDENCE.
• Missing privacy class: event contains a pseudonymous learner reference but no data-classification decision. → HOLD_PRIVACY_CLASS.
• High-cardinality data hidden in names: session, learner, document, or error text enters the name namespace. → HOLD_CARDINALITY_POLICY.
• Derived metric overwrites raw evidence: aggregation destroys occurrence-level provenance. → HOLD_DERIVATION_PROVENANCE.
• Completion equals mastery: a click or completion signal is treated as learning proof. → HOLD_MASTERY_INFERENCE.
• Replay rewrites history: older producer events are transformed with no trace of original version/meaning. → HOLD_REPLAY_PROVENANCE.

A deterministic validator can identify these contract violations. It cannot decide the educational meaning of mastery without the separate governed evidence model.

Alternatives and trade-offs

One giant event with many attributes. Fewer event names can simplify instrumentation, but an over-generic event can make semantics opaque and validation weak. Use shared names only where the event definition truly remains the same.

One event name per object instance. This looks easy to query by string prefix, but explodes cardinality and makes the event namespace carry data. Stable semantic names plus attributes are more replayable.

Rewrite all historical events into the latest schema. This simplifies a dashboard at the cost of provenance. Prefer an immutable raw layer plus explicit normalized/migrated views whose transformation version is recorded.

Infer product or learning outcomes directly from raw events. Fast, but dangerous. A raw event may be missing, duplicated, delayed, instrumented inconsistently, or simply not semantically sufficient. Derived metrics should name their formula/window/source versions, and learning claims should use a separate evidence contract.

Use only a learning interoperability standard or only an observability standard. Caliper helps describe learning activities; OpenTelemetry helps structure telemetry/event representation. Neither, alone, owns MAKNOW's local event governance and interpretation policy. Mapping is optional and bounded by semantic fit.

Experienced bridge: taxonomy governance is a contract across producers and time

At scale, the difficult problem is not emitting JSON. It is preserving meaning while teams, SDKs, clients, and dashboards evolve independently.

Use a registry or equivalent governed catalog where each event definition has: stable name, definition, owner, taxonomy version, schema version, allowed attributes, cardinality/privacy classification, producer compatibility, deprecation state, replacement, and change history. CI or instrumentation tests can validate producer payloads against that contract before release.

For offline/replayed events, store both occurrence and observation semantics. For migration, prefer functions that are deterministic, versioned, and provenance-preserving. If an old event cannot be mapped without changing meaning, leave it as the old event and mark the normalized interpretation as partial or not available.

For derived metrics, record metric identity/version, input event versions, time window, deduplication/idempotency rule, late-arrival policy, and transformation provenance. That makes historical comparisons explainable when producer versions change.

Guided and independent practice

Guided pass. Open lab://MKN-020/MKN-020-LAB1. Start with the canonical baseline. Populate the contract and verify that the stable event name, versions, timestamps, privacy/cardinality class, provenance, and mastery boundary are all visible. The deterministic gate should stop at TAXONOMY_REVIEW_REQUIRED, not auto-promote.

Then inspect the dynamic-name mutation. Move the lesson identifier out of the name and into object_ref; keep a legacy mapping record rather than pretending the old event never existed.

Independent pass. Diagnose at least four mutations: missing observed timestamp, rename without migration, completion→mastery inference, and missing privacy class. For each, state the failed dimension, typed result, minimum repair, and what historical evidence must remain immutable.

Transfer. A mobile client went offline under taxonomy v2 and uploads after v3 exists. Recompute from the changed evidence: preserve v2 name/schema/producer semantics, maintain event vs observed timestamps, attach migration provenance if a compatible v3 view is produced, and reject any baseline-answer reuse that silently rewrites old meaning.

Verification and evidence

The primary artifact is MKN-020-T1 — Learning & Product Event Taxonomy Governance Contract v1. It contains three scenarios: canonical baseline, invalid dynamic-name/mastery shortcut, and offline transfer after taxonomy revision.

Verification requires:

• all 21 frozen critical dimensions remain visible;
• event names contain semantic identity rather than per-occurrence dynamic values;
• event and observed timestamps remain distinct;
• taxonomy/schema/producer versions remain independently traceable;
• privacy/cardinality and validation states are explicit;
• deprecation/replacement/migration do not erase original meaning;
• derived metrics point downstream instead of mutating raw events;
• mastery remains forbidden without separate evidence;
• missing evidence yields typed HOLD/REVIEW_REQUIRED;
• transfer is recomputed from changed evidence and rejects baseline-oracle reuse.

The deterministic oracle is the frozen Bible plus visible synthetic fixture values—not hidden model reasoning and not a live analytics backend.

Assessment and transfer gate

S1 — retrieval. Explain the owned boundary of Learning/Product Analytics Event Taxonomy and one non-goal. S2 — application. Build Learning & Product Event Taxonomy Governance Contract v1 for the baseline synthetic fixture. S3 — diagnosis. Replace a stable event name with a dynamic name containing a lesson identifier. Identify the broken dimension, consequence, and minimum repair. S4 — transfer. A mobile client uploads events after a taxonomy revision. Preserve event time vs observed time, producer version, old meaning, and migration provenance; do not silently rewrite v2 events into v3.

Passing requires exact identity/version/timestamp/provenance evidence, explicit negative cases, a decision no stronger than evidence, and genuine recomputation in transfer. A human reviewer must be able to reproduce the result without hidden model reasoning.

References, freshness, and authority boundaries

FACT — 1EdTech Caliper Analytics. Rechecked 2026-09-13. The current 1EdTech standards pages still present Caliper Analytics 1.2 and metric profiles/common vocabulary for consistently representing learning activities. Caliper does not define MAKNOW mastery policy, KPI formulas, privacy policy, retention, or taxonomy promotion authority.

FACT — OpenTelemetry semantic conventions for events. Rechecked 2026-09-13. The current page is marked Development. It describes named point-in-time occurrences, requires an event name, forbids dynamic values in event names, requires event timestamp to represent occurrence time, and separates observed/received time semantics. It does not define MAKNOW learning interpretation.

INFERENCE — versioned semantic layer. MAKNOW uses these representation patterns to justify stable names, structured attributes, separate occurrence/observation time, and versioned migration provenance so comparisons can survive producer evolution. This is an engineering inference, not a quoted standard requirement for MAKNOW.

DESIGN — MAKNOW event governance. Namespace, critical dimensions, privacy/cardinality classes, validation states, deprecation/migration/replay policy, metric definitions, retention, and mastery boundaries are local design authority. Accepted package bytes are never silently mutated when an external source changes.