Structure: schemas, models, and grouping rules
The structural documentation describes the canonical elements used to represent observed activity. It defines the core record types, metadata fields, and relational links required for reproducible internal inspection. Core record types include event records, entity descriptors, and mapping tables that associate actor identifiers with contextual attributes. Metadata fields annotate capture method, schema version, and provenance markers so each entry can be traced to a specific observational procedure. Records are designed to support deterministic joins and derived timeline views without introducing interpretation beyond stated annotation provenance.
Taxonomy formalization
Taxonomy formalization documents controlled vocabularies that label atomic actions and higher-order classes. Each label is defined with a canonical identifier, human-readable name, and a concise definition that specifies observable criteria for assignment. Definitions include whether a label applies to an instantaneous event or to an interval, and they indicate required metadata such as actor_type or location qualifiers. Taxonomy entries include validation examples that show representative records and edge cases that require reviewer judgement. Changes to taxonomy entries are versioned with mapping rules to prior identifiers to permit longitudinal comparisons of annotated records. The formalization ensures that labels are operationally explicit and that their application can be replicated by different observers using the same protocol.
Controlled vocabulary
Vocabulary entries are explicit and include provenance metadata and example records to reduce ambiguity during annotation.
- Identifier, label, definition, applicability
- Example records and edge cases
- Version mappings and change rationale
Temporal modeling and timeline constructs
Temporal modeling distinguishes discrete events, bounded intervals, and session views. Event records carry canonical timestamps and optional duration fields when an interval model is required. Timelines are derived by ordering events and applying adjacency and concurrency rules that are explicitly documented. Windowing rules specify how to form intervals from adjacent events, the tolerance for gaps, and the criteria for session boundaries. Derived timeline views include ordered event lists, merged intervals based on adjacency thresholds, and concurrency matrices that indicate overlaps between actor roles. All transformation logic is codified in pseudocode or canonical SQL examples to support reproducible reproduction of timeline outputs during internal review.
Grouping rules and transformation recipes
Grouping rules specify deterministic criteria for aggregating atomic actions into logical composites. Rules define keys for grouping, adjacency thresholds for merging successive events, and role-continuity checks to preserve contextual coherence. Transformations are presented as recipes using canonical SQL or pseudocode with explicit inputs and outputs so practitioners can reproduce derived datasets. Recipes include index suggestions for efficient joins, normalization steps for entity mappings, and validation queries to detect timestamp anomalies or disconnected sequences. Each recipe is accompanied by notes on its intended use, assumptions, and examples of expected intermediate and final outputs to support internal verification and reproducible documentation workflows.