Defines a controlled event taxonomy with business occurrences, stable identities, typed properties, context boundaries, versioning, privacy purpose, and data-quality ownership for consistent measurement.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Name events as past-tense business occurrences and separate them from mutable interpretation. Register each event and property before production, use shared context only for genuinely universal fields, and version semantic breaking changes.
Scope
- Naming, occurrence semantics, producer, subject, event identity, time, context, properties, enums, versions, purpose, privacy class, ownership, and quality.
- Product and operational analytics events shared across producers and consumers.
- A registry that drives validation and documentation.
Outside this block
- Metric definitions derived downstream or copying UI control names into permanent event semantics.
- Putting every available entity attribute into each event.
Contract
- Each event represents one completed or observed occurrence and names producer, trigger, subject, actor role when allowed, and success/failure semantics.
- Event ID is unique per occurrence; retries preserve it, while multiple distinct occurrences use distinct IDs.
- Occurrence time and receive time are separate; timestamps use an unambiguous standard instant.
- Properties have type, allowed values, null/absence meaning, unit, privacy class, purpose, and owner.
- Entity identifiers are stable and pseudonymous where analytics does not require direct identity.
- Breaking semantic or type changes create a new event version; additive optional fields follow compatibility policy.
Implementation guidance
- Adopt a common envelope and a registry-backed payload schema.
- Keep environment, release, producer, schema version, consent/purpose profile, and test-traffic marker in controlled context.
- Validate at producer CI and ingestion; quarantine rather than coerce incompatible payloads.
- Define canonical examples and counterexamples for ambiguous events.
Failure handling and safeguards
- Unknown event type or required property fails validation and enters quarantine.
- If an occurrence outcome is unknown, use an explicit state or omit emission according to contract; never default it to success.
- If an identifier is accidentally reused, retain evidence and correct downstream counts through a versioned repair.
Verification and operations
- Measure schema rejection, unknown enum, duplicate event ID, late arrival, missing property, producer version coverage, and event-volume discontinuity.
- Assign owner and deprecation date to every event version.
- Reconcile critical occurrence counts with operational sources.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.