Base Event, metadata description updates

dictionary.json

@@ -164,7 +164,7 @@
     },
     "activity_name": {
       "caption": "Activity",
-      "description": "The event activity name, as defined by the activity_id.",
+      "description": "The event activity name, as defined by the <code>activity_id</code>. When <code>activity_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific activity label. For all other <code>activity_id</code> values, this should match the caption defined for that <code>activity_id</code> enum value.",
       "type": "string_t"
     },
     "actor": {
@@ -1070,7 +1070,7 @@
     },
     "category_name": {
       "caption": "Category",
-      "description": "The event category name, as defined by category_uid value.",
+      "description": "The event category name, as defined by the <code>category_uid</code> value. The value should match the caption defined for the corresponding <code>category_uid</code> enum value (e.g., <code>\"Findings\"</code> for <code>category_uid: 2</code>).",
       "type": "string_t"
     },
     "category_uid": {
@@ -1196,7 +1196,7 @@
     },
     "class_name": {
       "caption": "Class",
-      "description": "The event class name, as defined by class_uid value.",
+      "description": "The event class name, as defined by the <code>class_uid</code> value. The value should match the caption defined for the corresponding <code>class_uid</code> (e.g., <code>\"Detection Finding\"</code> for <code>class_uid: 2004</code>).",
       "type": "string_t"
     },
     "class_uid": {
@@ -1529,7 +1529,7 @@
     },
     "count": {
       "caption": "Count",
-      "description": "The number of times that events in the same logical group occurred during the event <strong>Start Time</strong> to <strong>End Time</strong> period.",
+      "description": "The count of a grouped or aggregated item. See specific usage.",
       "type": "integer_t"
     },
     "countermeasures": {
@@ -4065,7 +4065,7 @@
     },
     "message": {
       "caption": "Message",
-      "description": "The description of the event/finding, as defined by the source.",
+      "description": "The descriptive message associated with the event or object. See specific usage.",
       "type": "string_t"
     },
     "message_context": {
@@ -4099,7 +4099,7 @@
     },
     "metadata": {
       "caption": "Metadata",
-      "description": "The metadata associated with the event or a finding.",
+      "description": "The metadata object describes the event producer, schema version, and processing information. Producers <b>must</b> populate <code>metadata.product</code> to identify the data source, and <code>metadata.version</code> to indicate the OCSF schema version used. Consumers rely on this to interpret the event correctly.",
       "type": "metadata"
     },
     "metadata_endpoint": {
@@ -4308,7 +4308,7 @@
     },
     "observables": {
       "caption": "Observables",
-      "description": "The observables associated with the event or a finding.",
+      "description": "The observables array surfaces key indicators and entities from the event or finding in a single, consistent location for downstream correlation and detection. Each entry references an attribute path within the event (e.g., <code>src_endpoint.ip</code>) along with its type and value, enabling consumers to extract IOCs without parsing the full event structure.",
       "type": "observable",
       "references": [
         {
@@ -5203,17 +5203,17 @@
     },
     "raw_data": {
       "caption": "Raw Data",
-      "description": "The raw event/finding data as received from the source.",
+      "description": "The original event/finding data as received from the source, before normalization into OCSF. Populate this with the verbatim log line, JSON payload, or other native format for forensic and debugging purposes. This field is not intended for structured querying &mdash; use the normalized OCSF attributes instead.",
       "type": "string_t"
     },
     "raw_data_hash": {
       "caption": "Raw Data Hash",
-      "description": "The hash, which describes the content of the raw_data field.",
+      "description": "A fingerprint (hash) of the <code>raw_data</code> content. Use this to verify the integrity of the original event data or to deduplicate events. Only populate when <code>raw_data</code> is also set.",
       "type": "fingerprint"
     },
     "raw_data_size": {
       "caption": "Raw Data Size",
-      "description": "The size of the raw data which was transformed into an OCSF event, in bytes.",
+      "description": "The size of the original event data (as captured in <code>raw_data</code>) in bytes, before OCSF normalization. Useful for metering and capacity planning. Only populate when <code>raw_data</code> is also set.",
       "type": "long_t"
     },
     "raw_header": {
@@ -5929,7 +5929,7 @@
     },
     "severity": {
       "caption": "Severity",
-      "description": "The event/finding severity, normalized to the caption of the <code>severity_id</code> value. In the case of 'Other', it is defined by the source.",
+      "description": "The event/finding severity label, normalized to the caption of the <code>severity_id</code> value. When <code>severity_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific severity label. For all other values, this should match the caption defined for that <code>severity_id</code> enum value (e.g., <code>\"High\"</code> for <code>severity_id: 4</code>).",
       "type": "string_t"
     },
     "severity_id": {
@@ -6245,7 +6245,7 @@
     },
     "status": {
       "caption": "Status",
-      "description": "The event status, normalized to the caption of the status_id value. In the case of 'Other', it is defined by the event source.",
+      "description": "The event status label, normalized to the caption of the <code>status_id</code> value. When <code>status_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific status label. For all other values, this should match the caption defined for that <code>status_id</code> enum value (e.g., <code>\"Success\"</code> for <code>status_id: 1</code>).",
       "type": "string_t"
     },
     "status_code": {
@@ -6255,7 +6255,7 @@
     },
     "status_detail": {
       "caption": "Status Detail",
-      "description": "The status detail contains additional information about the event/finding outcome.",
+      "description": "A human-readable description providing additional context about the event/finding outcome. Use this to convey details that go beyond the normalized <code>status_id</code> and source-specific <code>status_code</code>, such as a failure reason or error message.",
       "type": "string_t"
     },
     "status_details": {
@@ -6587,7 +6587,7 @@
     },
     "timezone_offset": {
       "caption": "Timezone Offset",
-      "description": "The number of minutes that the reported event <code>time</code> is ahead or behind UTC, in the range -1,080 to +1,080.",
+      "description": "The number of minutes that the reported event <code>time</code> is ahead or behind UTC, in the range -1,080 to +1,080. This allows consumers to reconstruct the local time at the event source. For example, US Eastern Standard Time is <code>-300</code>. Populate this when the source provides local time zone information.",
       "type": "integer_t"
     },
     "title": {
@@ -6746,12 +6746,12 @@
     },
     "type_name": {
       "caption": "Type Name",
-      "description": "The event/finding type name, as defined by the type_uid.",
+      "description": "The event/finding type name, combining the class and activity (e.g., <code>\"Detection Finding: Create\"</code>). The value should match the <code>class_name</code> and <code>activity_name</code> joined by <code>\": \"</code>.",
       "type": "string_t"
     },
     "type_uid": {
       "caption": "Type ID",
-      "description": "The event/finding type ID. It identifies the event's semantics and structure. The value is calculated by the logging system as: <code>class_uid * 100 + activity_id</code>.",
+      "description": "The event/finding type ID. It identifies the event's semantics and structure. Producers <b>must</b> compute this as <code>class_uid * 100 + activity_id</code>. It uniquely identifies the combination of event class and activity across the entire schema. For example, <code>Detection Finding: Create</code> is <code>200401</code>.",
       "sibling": "type_name",
       "type": "long_t"
     },
@@ -6804,7 +6804,7 @@
     },
     "unmapped": {
       "caption": "Unmapped Data",
-      "description": "The attributes that are not mapped to the event schema. The names and values of those attributes are specific to the event source.",
+      "description": "A container for source-specific attributes that do not map to any defined OCSF attribute. Use this to preserve valuable source data that would otherwise be lost during normalization. The keys and values are specific to the event source. Consumers should not rely on a stable structure within this field.",
       "type": "object"
     },
     "untruncated_size": {

events/base_event.json

@@ -12,6 +12,7 @@
       "profiles/security_control.json"
     ],
     "activity_id": {
+      "description": "The normalized identifier of the activity that triggered the event. Each event class defines its own set of activity values. Use <code>0</code> (Unknown) when the activity cannot be determined, and <code>99</code> (Other) when the activity does not match any defined value &mdash; in that case, populate <code>activity_name</code> with the source-specific label.",
       "group": "classification",
       "requirement": "required",
       "enum": {
@@ -32,6 +33,7 @@
       "requirement": "optional"
     },
     "category_uid": {
+      "description": "The category unique identifier of the event. Each event class belongs to exactly one category. Producers must set this to the category defined by the event class being used. Use <code>0</code> (Uncategorized) only for the base event class.",
       "group": "classification",
       "requirement": "required",
       "enum": {
@@ -45,6 +47,7 @@
       "requirement": "optional"
     },
     "class_uid": {
+      "description": "The unique identifier of the event class. A class describes the attributes available in an event. Producers must set this to the <code>uid</code> defined in the event class definition. For example, <code>Detection Finding</code> is <code>2004</code>.",
       "group": "classification",
       "requirement": "required",
       "enum": {
@@ -54,16 +57,17 @@
       }
     },
     "count": {
+      "description": "The number of events aggregated into this single record. Only populate for aggregate events; when set, <code>start_time</code> and <code>end_time</code> should also be provided to define the aggregation window.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "duration": {
-      "description": "The event duration or aggregate time, the amount of time the event covers from <code>start_time</code> to <code>end_time</code> in milliseconds.",
+      "description": "The elapsed time of the aggregation window in milliseconds, from <code>start_time</code> to <code>end_time</code>. Only populate for aggregate events (<code>count</code> &gt; 1). The value should equal <code>end_time - start_time</code>.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "end_time": {
-      "description": "The end time of a time period, or the time of the most recent event included in the aggregate event.",
+      "description": "The time of the most recent event in an aggregate (<code>count</code> &gt; 1). Do not populate for discrete, point-in-time events &mdash; use <code>time</code> alone. Subclasses such as findings may redefine this for their own time-range semantics.",
       "group": "occurrence",
       "requirement": "optional"
     },
@@ -72,6 +76,7 @@
       "requirement": "optional"
     },
     "message": {
+      "description": "A human-readable description of the event, as defined by the source. This should be a concise, meaningful summary suitable for display in a UI or alert notification &mdash; not a raw log line. For example: <code>\"User john_doe logged in from 10.0.0.1\"</code> rather than a raw syslog string.",
       "group": "primary",
       "requirement": "recommended"
     },
@@ -100,31 +105,37 @@
       "requirement": "optional"
     },
     "severity_id": {
+      "description": "The normalized severity of the event. Producers must map their source severity to one of the defined values: <code>1</code> (Informational), <code>2</code> (Low), <code>3</code> (Medium), <code>4</code> (High), <code>5</code> (Critical), or <code>6</code> (Fatal). Use <code>0</code> (Unknown) when severity cannot be determined, and <code>99</code> (Other) with a populated <code>severity</code> string when the source value does not map to a defined level.",
       "group": "classification",
       "requirement": "required"
     },
     "start_time": {
-      "description": "The start time of a time period, or the time of the least recent event included in the aggregate event.",
+      "description": "The time of the earliest event in an aggregate (<code>count</code> &gt; 1). Do not populate for discrete, point-in-time events &mdash; use <code>time</code> alone. Subclasses such as findings may redefine this for their own time-range semantics.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "status": {
+      "description": "The event status label, normalized to the caption of the <code>status_id</code> value. When <code>status_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific status label. For all other values, this should match the caption defined for that <code>status_id</code> enum value (e.g., <code>\"Success\"</code> for <code>status_id: 1</code>). Use this family of attributes to convey the outcome of the activity described by the event.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_code": {
+      "description": "The source-specific status or error code as reported by the event source. For example, a Windows logon failure code (<code>0x18</code>), an HTTP response code (<code>403</code>), or an AWS API error code. This preserves the original code for detailed troubleshooting beyond what <code>status_id</code> conveys.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_detail": {
+      "description": "A human-readable description providing additional context about the event outcome. Use this to convey details that go beyond the normalized <code>status_id</code> and source-specific <code>status_code</code>, such as a failure reason or error message. For example: <code>\"Account locked after 5 failed attempts\"</code>.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_id": {
+      "description": "The normalized status of the event outcome. Producers should map their source outcome to <code>1</code> (Success) or <code>2</code> (Failure). Use <code>0</code> (Unknown) when the outcome cannot be determined, and <code>99</code> (Other) with a populated <code>status</code> string when the source value does not map cleanly.",
       "group": "primary",
       "requirement": "recommended"
     },
     "time": {
+      "description": "The primary timestamp of the event &mdash; when the activity actually occurred at the source. For aggregate events (<code>count</code> &gt; 1), set this to <code>start_time</code> (the earliest event in the aggregate) to preserve causal ordering and consistent timeline alignment. This is the most important temporal attribute and <b>must</b> be a UTC epoch value in milliseconds (e.g., <code>1618524549901</code>). Mappers should use the most precise and authoritative timestamp available from the source. Do not confuse with <code>metadata.logged_time</code> (when the event was ingested) or <code>metadata.processed_time</code> (when it was normalized).",
       "group": "occurrence",
       "requirement": "required"
     },

events/findings/finding.json

@@ -9,7 +9,7 @@
       "profiles/incident.json"
     ],
     "activity_id": {
-      "description": "The normalized identifier of the finding activity.",
+      "description": "The normalized identifier of the finding activity. Use <code>1</code> (Create) when a finding is first generated, <code>2</code> (Update) when an existing finding is modified (e.g., severity change, new evidence), and <code>3</code> (Close) when a finding is resolved or dismissed.",
       "enum": {
         "1": {
           "caption": "Create",
@@ -26,7 +26,7 @@
       }
     },
     "activity_name": {
-      "description": "The finding activity name, as defined by the <code>activity_id</code>."
+      "description": "The finding activity name, as defined by the <code>activity_id</code>. When <code>activity_id</code> is <code>99</code> (Other), this <b>must</b> contain the source-specific activity label."
     },
     "comment": {
       "description": "A user provided comment about the finding.",
@@ -55,24 +55,24 @@
       "profile": null
     },
     "end_time": {
-      "description": "The time of the most recent event included in the finding.",
+      "description": "The time of the most recent event or finding that contributed to this finding.",
       "requirement": "optional"
     },
     "finding_info": {
       "group": "primary",
       "requirement": "required"
     },
     "start_time": {
-      "description": "The time of the least recent event included in the finding.",
+      "description": "The time of the earliest event or finding that contributed to this finding.",
       "requirement": "optional"
     },
     "status": {
-      "description": "The normalized status of the Finding set by the consumer normalized to the caption of the status_id value. In the case of 'Other', it is defined by the source.",
+      "description": "The finding lifecycle status label, normalized to the caption of the <code>status_id</code> value. Unlike event-level status (which indicates success/failure of an activity), finding status tracks the review workflow: whether the finding is new, being investigated, suppressed, or resolved. When <code>status_id</code> is <code>99</code> (Other), this <b>must</b> contain the source-specific status label.",
       "group": "context",
       "requirement": "optional"
     },
     "status_id": {
-      "description": "The normalized status identifier of the Finding, set by the consumer.",
+      "description": "The normalized finding lifecycle status identifier. This tracks the review and triage workflow of the finding, not the outcome of the underlying activity. Producers should set this to reflect the current state of the finding in their system (e.g., <code>1</code> for newly created findings, <code>4</code> when remediated).",
       "group": "context",
       "requirement": "recommended",
       "enum": {