Skip to content

6.6.2.1 CanonicalEvent

6.6.2.1.1 Purpose

Something that happened to an animal, a group or a product lot at a point in time, as reported by one feed: a calving, a service, a treatment, an exit from the herd. Events are evidence: several of them can describe the same fact, and they are joined into a resolved event, which is what consumers read.

6.6.2.1.2 Questions it answers

  • What did each source report happening to this animal, and when?
  • When was the event recorded at the source?
  • Which provider code and raw record does it come from?
  • Has the source corrected or cancelled it?

6.6.2.1.3 Fields

Field Type Cardinality Description
id string (uuid) 1..1 Key.
source_producer SourceProducerEntity 1..1 The producer of the canonical event.
occurred EventTime 1..1 When it happened, with its precision: many sources give only a date.
recorded_at datetime 0..1 When it was entered at the source; may differ from occurred (e.g. inseminations are registered 4-19 days late, median per farm).
Empty when the source does not say (e.g. SiAlleva exits); never filled with an assumed delay.
status enum 1..1 Values: active, corrected, cancelled. Default: active.
Sources resend and correct events; a correction never deletes history.
cancelled: a verified authoritative full snapshot proves removal (SyncRun), or the source sent an explicit deletion.
raw_metadata RawMetadata 0..1 Required unless computed by us (e.g. our heat alert); see lineage.
raw_locator string 0..1
source_record_key string 1..1 Logical identity (source_feed, source_record_key); historical uniqueness adds revision number.
Source-key recipes are documented; collisions are issues, not automatically duplicate events.
source_code string 0..1 The provider's own code for the event (e.g. AfiFarm 30017, DairyComp PARTO), for traceability.
Map documented meaning and export version, not labels. Provider-specific findings become adapter tests.
Later outcomes on earlier services become known at their revision availability, not the service date.
source_feed SourceFeed 1..1
content_hash string 1..1 Same rule as CanonicalObservation.content_hash.
revision RecordRevision 1..1
farm Farm 1..1 The farm of the feed that delivered the record (= source_feed.farm), copied here as the key of partitioning, row-level access and erasure; it never changes on a revision. See STORAGE.
For events we compute (e.g. our heat alert), the farm of the inputs.
created_at datetime 1..1
updated_at datetime 1..1

6.6.2.1.4 Subtypes

Discriminator subject: every CanonicalEvent is exactly one of the subtypes below (disjoint and complete).

AnimalEvent

Field Type Cardinality Description
animal Animal 1..1

Discriminator type: every AnimalEvent is exactly one of the subtypes below (disjoint and complete).

HerdEntryEvent

Field Type Cardinality Description
entry_reason enum 1..1 Values: purchase, transfer_in, other, unknown.
  • Birth on the farm is a ParturitionEvent of the dam, not an entry.

HerdExitEvent

Exit from a management episode; not every exit asserts global death.

Field Type Cardinality Description
exit_type enum 1..1 Values: sale_alive, transfer_out, sent_to_slaughter, emergency_slaughter, slaughter_confirmed, death, other, unknown.
Map each country's export explicitly; dispatch to slaughter does not prove confirmed slaughter.
emergency_slaughter: slaughter of an injured or sick animal under the veterinary emergency rules (in Italy code 5).
A source code may change meaning by farm and period (e.g. one farm records planned culls as transfers since 2018; code 5 rules changed in 2022 and 2026): parser mappings can be scoped by farm and validity period, and source_code is kept so the mapping can be re-applied.
death_type DeathType 0..1 Only when exit_type = death.
cause string 0..1
destination string 0..1
management_episode AnimalOwnership 0..1
exited_group AnimalGroup 0..1
  • Resolve historical farm context before closing an episode; group moves do not imply farm exit.
  • Disputed mortality is not silently promoted to a verified training label.

ServiceEvent

Covers artificial insemination, natural service and embryo transfer.

Field Type Cardinality Description
service_method enum 1..1 Values: artificial_insemination, natural_service, embryo_transfer, unknown.
sire ParentReference 0..1
semen_type enum 1..1 Values: conventional, sexed_female, sexed_male, unknown. Default: unknown.
Sexed semen of both sexes is sold (SiAlleva Sex Fem, Sex Msc).
embryo_donor ParentReference 0..1 Only for embryo_transfer: the genetic mother. The animal of the event is the recipient.
reported_outcome CodedValue 0..1 Known at this revision's availability, not a new examination without evidence.

PregnancyCheckEvent

Field Type Cardinality Description
result enum 1..1 Values: pregnant, not_pregnant, uncertain.
related_service ServiceEvent 0..1

ParturitionEvent

The animal of the event is the dam that gave birth.

Field Type Cardinality Description
related_service ServiceEvent 0..1 The service that caused the pregnancy. Official PA/PN codes depend on it.
calving_ease CodedValue 0..1 Code plus code system, e.g. ICAR, PRES A-E, Lely BreCode.
offspring Offspring 0..* One row per newborn, alive or dead.

AbortionEvent

Field Type Cardinality Description
related_service ServiceEvent 0..1 Official AA/AY codes depend on it.

DryOffEvent

No fields beyond those of the parent.

HeatEvent

Field Type Cardinality Description
detection enum 1..1 Values: visual, sensor_alert, unknown.
  • A heat observed by a person or alerted by a system. A vendor heat alert is canonical as a fact; its proprietary score is not (it stays raw). Continuous activity quantities are CanonicalObservations, not events.

DiagnosisEvent

Field Type Cardinality Description
condition CodedValue 1..1
body_site BodySite 0..1
supporting_observations CanonicalObservation 0..* Observations used as evidence, e.g. a lab SCC. The diagnosis points to them, not the opposite.

TreatmentEvent

Field Type Cardinality Description
treatment_kind enum 1..1 Values: drug, vaccination, procedure, reproductive_protocol.
related_diagnosis DiagnosisEvent 0..1
body_site BodySite 0..1
ends_at EventTime 0..1
products TreatmentProduct 0..*
  • Actual administration may support withdrawal periods under a documented rule; a prescription alone does not prove administration.

HealthCheckEvent

A veterinary or routine examination (e.g. post-partum check), with or without a finding.

Field Type Cardinality Description
finding CodedValue 0..1

BreedingStatusEvent

Field Type Cardinality Description
status enum 1..1 Values: ok_to_breed, do_not_breed.
  • Aligns with the ICAR DoNotBreed event.

AnimalGroupEvent

Field Type Cardinality Description
group AnimalGroup 1..1 A group event without a group is meaningless.

Discriminator type: an AnimalGroupEvent is at most one of the subtypes below (disjoint, not complete), so records with none of them are allowed.

GroupTreatmentEvent

Field Type Cardinality Description
treatment_kind enum 1..1 Values: drug, vaccination, procedure.
products TreatmentProduct 0..*
  • e.g. a mass vaccination recorded once for a whole group.

GroupMovementEvent

Future work

Part of the model, but built only when a real case needs it. Only for collective batches.

Animals entering or leaving a collective group by count, without individual identity (e.g. chicks placed, birds dead).

Field Type Cardinality Description
direction enum 1..1 Values: entry, exit.
count integer 1..1 Greater than 0.
reason enum 1..1 Values: placement, purchase, transfer, sale_alive, sent_to_slaughter, emergency_slaughter, death, culling, other, unknown.
Placement and purchase only for entry; the others only for exit except transfer and other.
destination string 0..1
  • Individually identified animals keep HerdEntryEvent / HerdExitEvent and AnimalGroupMembership.

ProductEvent

Future work

Part of the model, but built only when a real case needs it. No product lot events yet.

Field Type Cardinality Description
product_material ProductMaterial 1..1
  • Something that happened to a product lot (e.g. a milk shipment rejected, an egg lot withdrawn).

Future work

Typed subtypes per product.

6.6.2.1.5 Relationships

References

Referenced by

Uses types

EventTime, RecordRevision, ParentReference, CodedValue

Subtypes

6.6.2.1.6 Rules & constraints

  • Something that happened to a subject at a point in time.
  • Each event type has its own fields, so events keep typed subtypes (unlike observations).
  • Event types align with the ICAR Animal Data Exchange event resources.
  • A CanonicalEvent is evidence: what one feed says. Several events can describe the same real fact; they are linked to one ResolvedEvent. Consumers read ResolvedEvents.
  • An event inferred by the source (e.g. a calving computed from days in milk) has a ComputedSourceOrigin (computed_by = vendor).
  • Group moves of identified animals are not events: they are AnimalGroupMembership.
  • Ownership transfers are not events: they are Ownership.