From c2b547f03c1d4fe3212383f0f5d8c6ce0a63e6ce Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Thu, 12 Dec 2019 15:20:10 -0500
Subject: [PATCH 01/27] Fill in categorization values that are expected over
 time

---
 docs/field-details.asciidoc  |  18 +-
 docs/field-values.asciidoc   | 363 ++++++++++++++++++++++++++++++++++-
 generated/ecs/ecs_flat.yml   | 201 ++++++++++++++++++-
 generated/ecs/ecs_nested.yml | 201 ++++++++++++++++++-
 schemas/event.yml            | 238 +++++++++++++++++++----
 5 files changed, 963 insertions(+), 58 deletions(-)

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index da3b4375b9..b7453f8546 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1144,7 +1144,13 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-authentication{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}process
+apm{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}application{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}audit{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}authentication
+certificate{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}cloud{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}database{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}driver
+email{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}file{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}host{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}iam_group
+iam_user{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}intrusion_detection{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}malware{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}network
+network_flow{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}package{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}process{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}registry
+service{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}session{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}socket{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}vulnerability
+web
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-category,accepted values for event.category>>
@@ -1270,7 +1276,8 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-alert{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}event
+alert{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}event{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}metric{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}state
+pipeline_error{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}signal
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-kind,accepted values for event.kind>>
@@ -1316,7 +1323,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-success{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}failure
+failure{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}unknown{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}success
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-outcome,accepted values for event.outcome>>
@@ -1423,7 +1430,10 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-start{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}end
+access{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}allowed{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}audit{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}change
+creation{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}deletion{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}denied{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}end
+error{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}info{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}installation{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}protocol
+start
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-type,accepted values for event.type>>
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 9860f1f2cb..a0bcf5a8d3 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -39,11 +39,74 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 
 
+[float]
+[[ecs-event-kind-metric]]
+==== metric
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-kind-state]]
+==== state
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-kind-pipeline_error]]
+==== pipeline_error
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-kind-signal]]
+==== signal
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
 [[ecs-accepted-values-event-category]]
 === Accepted Values for event.category
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
+[float]
+[[ecs-event-category-apm]]
+==== apm
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-application]]
+==== application
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-audit]]
+==== audit
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
 [float]
 [[ecs-event-category-authentication]]
 ==== authentication
@@ -58,6 +121,132 @@ allow{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}deny{nbsp}{nbsp}{nbsp}{nbsp
 
 
 
+[float]
+[[ecs-event-category-certificate]]
+==== certificate
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-cloud]]
+==== cloud
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-database]]
+==== database
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-driver]]
+==== driver
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-email]]
+==== email
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-file]]
+==== file
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-host]]
+==== host
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-iam_group]]
+==== iam_group
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-iam_user]]
+==== iam_user
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-intrusion_detection]]
+==== intrusion_detection
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-malware]]
+==== malware
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-network]]
+==== network
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-network_flow]]
+==== network_flow
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-package]]
+==== package
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
 [float]
 [[ecs-event-category-process]]
 ==== process
@@ -72,14 +261,122 @@ start{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}info{nbsp}{nbsp}{nbsp}{nbsp
 
 
 
+[float]
+[[ecs-event-category-registry]]
+==== registry
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-service]]
+==== service
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-session]]
+==== session
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-socket]]
+==== socket
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-vulnerability]]
+==== vulnerability
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-category-web]]
+==== web
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
 [[ecs-accepted-values-event-type]]
 === Accepted Values for event.type
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
 [float]
-[[ecs-event-type-start]]
-==== start
+[[ecs-event-type-access]]
+==== access
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-allowed]]
+==== allowed
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-audit]]
+==== audit
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-change]]
+==== change
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-creation]]
+==== creation
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-deletion]]
+==== deletion
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-denied]]
+==== denied
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
@@ -95,14 +392,59 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 
 
+[float]
+[[ecs-event-type-error]]
+==== error
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-info]]
+==== info
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-installation]]
+==== installation
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-protocol]]
+==== protocol
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-start]]
+==== start
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
 [[ecs-accepted-values-event-outcome]]
 === Accepted Values for event.outcome
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
 [float]
-[[ecs-event-outcome-success]]
-==== success
+[[ecs-event-outcome-failure]]
+==== failure
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
@@ -110,8 +452,17 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 
 [float]
-[[ecs-event-outcome-failure]]
-==== failure
+[[ecs-event-outcome-unknown]]
+==== unknown
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-outcome-success]]
+==== success
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index d9ffea8e34..9f261d3155 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1375,6 +1375,21 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+      '
+    name: apm
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: application
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: audit
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
       '
     expected_event_types:
     - allow
@@ -1384,12 +1399,112 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+      '
+    name: certificate
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: cloud
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: database
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: driver
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: email
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: file
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: host
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: iam_group
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: iam_user
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: intrusion_detection
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: malware
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: network
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: network_flow
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: package
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
       '
     expected_event_types:
     - start
     - info
     - end
     name: process
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: registry
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: service
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: session
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: socket
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: vulnerability
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: web
   dashed_name: event-category
   description: 'Event category.
 
@@ -1537,6 +1652,26 @@ event.kind:
 
       '
     name: event
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: metric
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: state
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: pipeline_error
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: signal
   dashed_name: event-kind
   description: 'The kind of the event.
 
@@ -1588,12 +1723,17 @@ event.outcome:
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
       '
-    name: success
+    name: failure
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
       '
-    name: failure
+    name: unknown
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: success
   dashed_name: event-outcome
   description: 'The outcome of the event.
 
@@ -1710,12 +1850,67 @@ event.type:
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
       '
-    name: start
+    name: access
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: allowed
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: audit
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: change
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: creation
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: deletion
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: denied
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
       '
     name: end
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: error
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: info
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: installation
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: protocol
+  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+      '
+    name: start
   dashed_name: event-type
   description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
     tempor incididunt ut labore et dolore magna aliqua.
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index d143132f2b..b55a6deee1 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1589,6 +1589,21 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+          '
+        name: apm
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: application
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: audit
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
           '
         expected_event_types:
         - allow
@@ -1598,12 +1613,112 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+          '
+        name: certificate
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: cloud
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: database
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: driver
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: email
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: file
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: host
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: iam_group
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: iam_user
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: intrusion_detection
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: malware
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: network
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: network_flow
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: package
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
           '
         expected_event_types:
         - start
         - info
         - end
         name: process
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: registry
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: service
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: session
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: socket
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: vulnerability
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: web
       dashed_name: event-category
       description: 'Event category.
 
@@ -1752,6 +1867,26 @@ event:
 
           '
         name: event
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: metric
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: state
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: pipeline_error
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: signal
       dashed_name: event-kind
       description: 'The kind of the event.
 
@@ -1803,12 +1938,17 @@ event:
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
           '
-        name: success
+        name: failure
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
           '
-        name: failure
+        name: unknown
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: success
       dashed_name: event-outcome
       description: 'The outcome of the event.
 
@@ -1927,12 +2067,67 @@ event:
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
           '
-        name: start
+        name: access
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: allowed
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: audit
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: change
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: creation
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: deletion
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: denied
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
           '
         name: end
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: error
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: info
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: installation
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: protocol
+      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+          '
+        name: start
       dashed_name: event-type
       description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
         eiusmod tempor incididunt ut labore et dolore magna aliqua.
diff --git a/schemas/event.yml b/schemas/event.yml
index d757f6cd1e..ec483eab30 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -48,14 +48,30 @@
         contains, without being specific to the contents of the event.
       example: event
       accepted_values:
-      - name: alert
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
-      - name: event
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
+        - name: alert
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: event
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: metric
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: state
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: pipeline_error
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: signal
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
 
     - name: category
       level: core
@@ -69,22 +85,114 @@
         category contains multiple actions.
       example: user-management
       accepted_values:
-      - name: authentication
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
-        expected_event_types:
-          - allow
-          - deny
-          - info
-      - name: process
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
-        expected_event_types:
-          - start
-          - info
-          - end
+        - name: apm
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: application
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: audit
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: authentication
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+          expected_event_types:
+            - allow
+            - deny
+            - info
+        - name: certificate
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: cloud
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: database
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: driver
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: email
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: file
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: host
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: iam_group
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: iam_user
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: intrusion_detection
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: malware
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: network
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: network_flow
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: package
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: process
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+          expected_event_types:
+            - start
+            - info
+            - end
+        - name: registry
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: service
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: session
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: socket
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: vulnerability
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: web
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
 
     - name: action
       level: core
@@ -110,15 +218,18 @@
       example: success
 
       accepted_values:
-      - name: success
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
-
-      - name: failure
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
+        - name: failure
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: unknown
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: success
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
 
     - name: type
       level: core
@@ -129,15 +240,58 @@
         sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
       accepted_values:
-      - name: start
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
-
-      - name: end
-        description: >
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-          incididunt ut labore et dolore magna aliqua.
+        - name: access
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: allowed
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: audit
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: change
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: creation
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: deletion
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: denied
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: end
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: error
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: info
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: installation
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: protocol
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
+        - name: start
+          description: >
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua.
 
     - name: module
       level: core

From 5c29f4d8ab1acc8938aec886dbf4c8527b1977d2 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Thu, 12 Dec 2019 16:31:30 -0500
Subject: [PATCH 02/27] Add in-page navigation TOC to the accepted values pages

---
 docs/field-values.asciidoc            | 59 +++++++++++++++++++++++++++
 scripts/generators/asciidoc_fields.py | 22 +++++++---
 2 files changed, 75 insertions(+), 6 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index a0bcf5a8d3..05b379da0b 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -21,6 +21,15 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
+*Table of Contents*
+
+* <<ecs-event-kind-alert,alert>>
+* <<ecs-event-kind-event,event>>
+* <<ecs-event-kind-metric,metric>>
+* <<ecs-event-kind-state,state>>
+* <<ecs-event-kind-pipeline_error,pipeline_error>>
+* <<ecs-event-kind-signal,signal>>
+
 [float]
 [[ecs-event-kind-alert]]
 ==== alert
@@ -80,6 +89,34 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
+*Table of Contents*
+
+* <<ecs-event-category-apm,apm>>
+* <<ecs-event-category-application,application>>
+* <<ecs-event-category-audit,audit>>
+* <<ecs-event-category-authentication,authentication>>
+* <<ecs-event-category-certificate,certificate>>
+* <<ecs-event-category-cloud,cloud>>
+* <<ecs-event-category-database,database>>
+* <<ecs-event-category-driver,driver>>
+* <<ecs-event-category-email,email>>
+* <<ecs-event-category-file,file>>
+* <<ecs-event-category-host,host>>
+* <<ecs-event-category-iam_group,iam_group>>
+* <<ecs-event-category-iam_user,iam_user>>
+* <<ecs-event-category-intrusion_detection,intrusion_detection>>
+* <<ecs-event-category-malware,malware>>
+* <<ecs-event-category-network,network>>
+* <<ecs-event-category-network_flow,network_flow>>
+* <<ecs-event-category-package,package>>
+* <<ecs-event-category-process,process>>
+* <<ecs-event-category-registry,registry>>
+* <<ecs-event-category-service,service>>
+* <<ecs-event-category-session,session>>
+* <<ecs-event-category-socket,socket>>
+* <<ecs-event-category-vulnerability,vulnerability>>
+* <<ecs-event-category-web,web>>
+
 [float]
 [[ecs-event-category-apm]]
 ==== apm
@@ -320,6 +357,22 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
+*Table of Contents*
+
+* <<ecs-event-type-access,access>>
+* <<ecs-event-type-allowed,allowed>>
+* <<ecs-event-type-audit,audit>>
+* <<ecs-event-type-change,change>>
+* <<ecs-event-type-creation,creation>>
+* <<ecs-event-type-deletion,deletion>>
+* <<ecs-event-type-denied,denied>>
+* <<ecs-event-type-end,end>>
+* <<ecs-event-type-error,error>>
+* <<ecs-event-type-info,info>>
+* <<ecs-event-type-installation,installation>>
+* <<ecs-event-type-protocol,protocol>>
+* <<ecs-event-type-start,start>>
+
 [float]
 [[ecs-event-type-access]]
 ==== access
@@ -442,6 +495,12 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
+*Table of Contents*
+
+* <<ecs-event-outcome-failure,failure>>
+* <<ecs-event-outcome-unknown,unknown>>
+* <<ecs-event-outcome-success,success>>
+
 [float]
 [[ecs-event-outcome-failure]]
 ==== failure
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index d2996df060..16ed9596d5 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -329,24 +329,31 @@ def values_header():
 
 def render_field_values_page(field):
     # Page heading
-    text = field_values_page_template().format(
+    heading = field_values_page_template().format(
         dashed_name=field['dashed_name'],
         flat_name=field['flat_name'],
         # description=field[''],
     )
+
     # Each accepted value
+    body = ''
+    toc = ''
     for value_details in field['accepted_values']:
+        toc += "* <<ecs-{field_dashed_name}-{value_name},{value_name}>>\n".format(
+            field_dashed_name=field['dashed_name'],
+            value_name=value_details['name']
+        )
         if 'expected_event_types' in value_details:
             additional_details = render_expected_event_types(value_details)
         else:
             additional_details = ''
-        text += field_values_template().format(
-            dashed_name=field['dashed_name'],
+        body += field_value_template().format(
+            field_dashed_name=field['dashed_name'],
             value_name=value_details['name'],
             value_description=value_details['description'],
             additional_details=additional_details
         )
-    return text
+    return heading + toc + body
 
 
 def render_expected_event_types(value_details):
@@ -373,13 +380,16 @@ def field_values_page_template():
 === Accepted Values for {flat_name}
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+*Table of Contents*
+
 '''
 
 
-def field_values_template():
+def field_value_template():
     return '''
 [float]
-[[ecs-{dashed_name}-{value_name}]]
+[[ecs-{field_dashed_name}-{value_name}]]
 ==== {value_name}
 
 {value_description}

From a2b27a4833fbf8862d62f579d7bf90e579bd651f Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 13:04:07 -0500
Subject: [PATCH 03/27] Get rid of spacing shenanigans. Commas work better.

---
 docs/field-details.asciidoc           | 18 ++++--------------
 docs/field-values.asciidoc            |  6 ++----
 scripts/generators/asciidoc_fields.py | 24 ++++++++++--------------
 3 files changed, 16 insertions(+), 32 deletions(-)

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index b7453f8546..4ec9d31c5e 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1144,13 +1144,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-apm{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}application{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}audit{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}authentication
-certificate{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}cloud{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}database{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}driver
-email{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}file{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}host{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}iam_group
-iam_user{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}intrusion_detection{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}malware{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}network
-network_flow{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}package{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}process{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}registry
-service{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}session{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}socket{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}vulnerability
-web
+apm, application, audit, authentication, certificate, cloud, database, driver, email, file, host, iam_group, iam_user, intrusion_detection, malware, network, network_flow, package, process, registry, service, session, socket, vulnerability, web
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-category,accepted values for event.category>>
@@ -1276,8 +1270,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-alert{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}event{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}metric{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}state
-pipeline_error{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}signal
+alert, event, metric, state, pipeline_error, signal
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-kind,accepted values for event.kind>>
@@ -1323,7 +1316,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-failure{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}unknown{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}success
+failure, unknown, success
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-outcome,accepted values for event.outcome>>
@@ -1430,10 +1423,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-access{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}allowed{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}audit{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}change
-creation{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}deletion{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}denied{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}end
-error{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}info{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}installation{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}protocol
-start
+access, allowed, audit, change, creation, deletion, denied, end, error, info, installation, protocol, start
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-type,accepted values for event.type>>
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 05b379da0b..d83f7bd45a 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -154,8 +154,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 *Expected event types for category authentication:*
 
-allow{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}deny{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}info
-
+allow, deny, info
 
 
 [float]
@@ -294,8 +293,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 *Expected event types for category process:*
 
-start{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}info{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}end
-
+start, info, end
 
 
 [float]
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 16ed9596d5..f86723694c 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -74,14 +74,12 @@ def render_asciidoc_paragraphs(string):
     return string.replace("\n", "\n\n")
 
 
-def render_accepted_values(field):
+def render_field_accepted_values(field):
     if not 'accepted_values' in field:
         return ''
-    rows_text = ''
-    for row in ecs_helpers.list_split_by(field['accepted_values'], 4):
-        rows_text += ("{nbsp}" * 8).join(ecs_helpers.list_extract_keys(row, 'name')) + "\n"
+    allowed_values = ', '.join(ecs_helpers.list_extract_keys(field['accepted_values'], 'name'))
     return field_acceptable_value_names().format(
-        rows_text=rows_text,
+        allowed_values=allowed_values,
         field_flat_name=field['flat_name'],
         field_dashed_name=field['dashed_name'],
     )
@@ -90,7 +88,7 @@ def render_accepted_values(field):
 def render_field_details_row(field):
     example = ''
     if 'accepted_values' in field:
-        example = render_accepted_values(field)
+        example = render_field_accepted_values(field)
     elif 'example' in field:
         example = "example: `{}`".format(str(field['example']))
 
@@ -252,7 +250,8 @@ def field_acceptable_value_names():
     return '''
 *Important*: The field value must be one of the following:
 
-{rows_text}
+{allowed_values}
+
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-{field_dashed_name},accepted values for {field_flat_name}>>
 '''
@@ -299,14 +298,14 @@ def nestings_row():
 
 
 def page_field_values(ecs_flat):
-    section_text = values_header()
+    section_text = values_section_header()
     category_fields = ['event.kind', 'event.category', 'event.type', 'event.outcome']
     for cat_field in category_fields:
         section_text += render_field_values_page(ecs_flat[cat_field])
     return section_text
 
 
-def values_header():
+def values_section_header():
     return '''
 [[ecs-category-field-values-reference]]
 == {ecs} Category Field Values
@@ -357,12 +356,9 @@ def render_field_values_page(field):
 
 
 def render_expected_event_types(value_details):
-    rows_of_types = ''
-    for row in ecs_helpers.list_split_by(value_details['expected_event_types'], 4):
-        rows_of_types += ("{nbsp}" * 8).join(row) + "\n"
     return expected_event_types_template().format(
         category_name=value_details['name'],
-        rows_of_types=rows_of_types,
+        expected_types=', '.join(value_details['expected_event_types']),
     )
 
 
@@ -370,7 +366,7 @@ def expected_event_types_template():
     return '''
 *Expected event types for category {category_name}:*
 
-{rows_of_types}
+{expected_types}
 '''
 
 

From 82a9e48c9b68dbf2f3bfb204c99819da9b1e71d2 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 13:10:07 -0500
Subject: [PATCH 04/27] Integrate public doc's wording as a placeholder for the
 top of the categorization section

---
 docs/field-values.asciidoc            | 8 +++++---
 scripts/generators/asciidoc_fields.py | 8 +++++---
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index d83f7bd45a..2e2cbca1cc 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -2,13 +2,15 @@
 [[ecs-category-field-values-reference]]
 == {ecs} Category Field Values
 
-In ECS, certain fields are not meant to be populated by the event source, but...
+At a high level, ECS provides fields to capture two types of event information:
+"Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
+and "What it is." Categorization Fields hold the "What it is" information.
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+ECS defines four Categorization Fields for this purpose, each of which falls under the `event.*` field set.
 
 [float]
 [[ecs-category-fields]]
-=== Category Fields
+=== Categorization Fields
 
 * <<ecs-accepted-values-event-kind,event.kind>>
 * <<ecs-accepted-values-event-category,event.category>>
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index f86723694c..c378f50334 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -310,13 +310,15 @@ def values_section_header():
 [[ecs-category-field-values-reference]]
 == {ecs} Category Field Values
 
-In ECS, certain fields are not meant to be populated by the event source, but...
+At a high level, ECS provides fields to capture two types of event information:
+"Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
+and "What it is." Categorization Fields hold the "What it is" information.
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+ECS defines four Categorization Fields for this purpose, each of which falls under the `event.*` field set.
 
 [float]
 [[ecs-category-fields]]
-=== Category Fields
+=== Categorization Fields
 
 * <<ecs-accepted-values-event-kind,event.kind>>
 * <<ecs-accepted-values-event-category,event.category>>

From 9176c2fdf15eddc1962a9856f6b782742cd0d544 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 13:18:42 -0500
Subject: [PATCH 05/27] Integrate current field description as the top of the
 categorization pages

---
 docs/field-values.asciidoc            | 14 ++++++++++----
 scripts/generators/asciidoc_fields.py |  4 ++--
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 2e2cbca1cc..b47c67edab 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -21,7 +21,9 @@ ECS defines four Categorization Fields for this purpose, each of which falls und
 [[ecs-accepted-values-event-kind]]
 === Accepted Values for event.kind
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+The kind of the event.
+
+This gives information about what type of information the event contains, without being specific to the contents of the event.
 
 *Table of Contents*
 
@@ -89,7 +91,9 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-accepted-values-event-category]]
 === Accepted Values for event.category
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Event category.
+
+This contains high-level information about the contents of the event. It is more generic than `event.action`, in the sense that typically a category contains multiple actions.
 
 *Table of Contents*
 
@@ -355,7 +359,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-accepted-values-event-type]]
 === Accepted Values for event.type
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
 *Table of Contents*
 
@@ -493,7 +497,9 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-accepted-values-event-outcome]]
 === Accepted Values for event.outcome
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+The outcome of the event.
+
+If the event describes an action, this fields contains the outcome of that action.
 
 *Table of Contents*
 
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index c378f50334..c665acb755 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -333,7 +333,7 @@ def render_field_values_page(field):
     heading = field_values_page_template().format(
         dashed_name=field['dashed_name'],
         flat_name=field['flat_name'],
-        # description=field[''],
+        field_description=render_asciidoc_paragraphs(field['description']),
     )
 
     # Each accepted value
@@ -377,7 +377,7 @@ def field_values_page_template():
 [[ecs-accepted-values-{dashed_name}]]
 === Accepted Values for {flat_name}
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+{field_description}
 
 *Table of Contents*
 

From 86688942eb532c6948d7eed2140558c80857759e Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 13:28:39 -0500
Subject: [PATCH 06/27] Trim down the list of categories to the ones we're
 introducing in 1.4

---
 docs/field-details.asciidoc  |   2 +-
 docs/field-values.asciidoc   | 150 -----------------------------------
 generated/ecs/ecs_flat.yml   |  75 ------------------
 generated/ecs/ecs_nested.yml |  75 ------------------
 schemas/event.yml            |  60 --------------
 5 files changed, 1 insertion(+), 361 deletions(-)

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index 4ec9d31c5e..6f61bc5346 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1144,7 +1144,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-apm, application, audit, authentication, certificate, cloud, database, driver, email, file, host, iam_group, iam_user, intrusion_detection, malware, network, network_flow, package, process, registry, service, session, socket, vulnerability, web
+authentication, database, driver, file, host, intrusion_detection, malware, package, process, web
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-category,accepted values for event.category>>
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index b47c67edab..23db5c1a77 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -97,59 +97,17 @@ This contains high-level information about the contents of the event. It is more
 
 *Table of Contents*
 
-* <<ecs-event-category-apm,apm>>
-* <<ecs-event-category-application,application>>
-* <<ecs-event-category-audit,audit>>
 * <<ecs-event-category-authentication,authentication>>
-* <<ecs-event-category-certificate,certificate>>
-* <<ecs-event-category-cloud,cloud>>
 * <<ecs-event-category-database,database>>
 * <<ecs-event-category-driver,driver>>
-* <<ecs-event-category-email,email>>
 * <<ecs-event-category-file,file>>
 * <<ecs-event-category-host,host>>
-* <<ecs-event-category-iam_group,iam_group>>
-* <<ecs-event-category-iam_user,iam_user>>
 * <<ecs-event-category-intrusion_detection,intrusion_detection>>
 * <<ecs-event-category-malware,malware>>
-* <<ecs-event-category-network,network>>
-* <<ecs-event-category-network_flow,network_flow>>
 * <<ecs-event-category-package,package>>
 * <<ecs-event-category-process,process>>
-* <<ecs-event-category-registry,registry>>
-* <<ecs-event-category-service,service>>
-* <<ecs-event-category-session,session>>
-* <<ecs-event-category-socket,socket>>
-* <<ecs-event-category-vulnerability,vulnerability>>
 * <<ecs-event-category-web,web>>
 
-[float]
-[[ecs-event-category-apm]]
-==== apm
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-application]]
-==== application
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-audit]]
-==== audit
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
 [float]
 [[ecs-event-category-authentication]]
 ==== authentication
@@ -163,24 +121,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 allow, deny, info
 
 
-[float]
-[[ecs-event-category-certificate]]
-==== certificate
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-cloud]]
-==== cloud
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
 [float]
 [[ecs-event-category-database]]
 ==== database
@@ -199,15 +139,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 
 
-[float]
-[[ecs-event-category-email]]
-==== email
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
 [float]
 [[ecs-event-category-file]]
 ==== file
@@ -226,24 +157,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 
 
-[float]
-[[ecs-event-category-iam_group]]
-==== iam_group
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-iam_user]]
-==== iam_user
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
 [float]
 [[ecs-event-category-intrusion_detection]]
 ==== intrusion_detection
@@ -262,24 +175,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 
 
-[float]
-[[ecs-event-category-network]]
-==== network
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-network_flow]]
-==== network_flow
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
 [float]
 [[ecs-event-category-package]]
 ==== package
@@ -302,51 +197,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 start, info, end
 
 
-[float]
-[[ecs-event-category-registry]]
-==== registry
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-service]]
-==== service
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-session]]
-==== session
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-socket]]
-==== socket
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-category-vulnerability]]
-==== vulnerability
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
 [float]
 [[ecs-event-category-web]]
 ==== web
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index 9f261d3155..c142c191c3 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1375,21 +1375,6 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      '
-    name: apm
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: application
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: audit
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
       '
     expected_event_types:
     - allow
@@ -1399,16 +1384,6 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      '
-    name: certificate
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: cloud
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
       '
     name: database
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
@@ -1419,11 +1394,6 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      '
-    name: email
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
       '
     name: file
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
@@ -1434,16 +1404,6 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      '
-    name: iam_group
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: iam_user
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
       '
     name: intrusion_detection
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
@@ -1454,16 +1414,6 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      '
-    name: network
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: network_flow
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
       '
     name: package
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
@@ -1478,31 +1428,6 @@ event.category:
   - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
       eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      '
-    name: registry
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: service
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: session
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: socket
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: vulnerability
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
       '
     name: web
   dashed_name: event-category
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index b55a6deee1..121704b29a 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1589,21 +1589,6 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-          '
-        name: apm
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: application
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: audit
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
           '
         expected_event_types:
         - allow
@@ -1613,16 +1598,6 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-          '
-        name: certificate
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: cloud
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
           '
         name: database
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
@@ -1633,11 +1608,6 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-          '
-        name: email
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
           '
         name: file
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
@@ -1648,16 +1618,6 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-          '
-        name: iam_group
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: iam_user
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
           '
         name: intrusion_detection
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
@@ -1668,16 +1628,6 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-          '
-        name: network
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: network_flow
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
           '
         name: package
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
@@ -1692,31 +1642,6 @@ event:
       - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
           do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-          '
-        name: registry
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: service
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: session
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: socket
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: vulnerability
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
           '
         name: web
       dashed_name: event-category
diff --git a/schemas/event.yml b/schemas/event.yml
index ec483eab30..ac06ebaf97 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -85,18 +85,6 @@
         category contains multiple actions.
       example: user-management
       accepted_values:
-        - name: apm
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: application
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: audit
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
         - name: authentication
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
@@ -105,14 +93,6 @@
             - allow
             - deny
             - info
-        - name: certificate
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: cloud
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
         - name: database
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
@@ -121,10 +101,6 @@
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
             incididunt ut labore et dolore magna aliqua.
-        - name: email
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
         - name: file
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
@@ -133,14 +109,6 @@
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
             incididunt ut labore et dolore magna aliqua.
-        - name: iam_group
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: iam_user
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
         - name: intrusion_detection
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
@@ -149,14 +117,6 @@
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
             incididunt ut labore et dolore magna aliqua.
-        - name: network
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: network_flow
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
         - name: package
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
@@ -169,26 +129,6 @@
             - start
             - info
             - end
-        - name: registry
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: service
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: session
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: socket
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: vulnerability
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
         - name: web
           description: >
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor

From a093adf19ea96d1afa0804c57aca7394c75fd759 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 13:35:11 -0500
Subject: [PATCH 07/27] Changelog

---
 CHANGELOG.next.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md
index 90dfe91226..107223fef2 100644
--- a/CHANGELOG.next.md
+++ b/CHANGELOG.next.md
@@ -22,6 +22,8 @@ Thanks, you're awesome :-) -->
 * Added `rule` fields. #665
 * Added default `text` analyzer as a multi-field to around 25 more fields. #680
 * Added `registry.*` fieldset for the Windows registry. #673
+* Publish initial list of allowed values for the reserved fields `event.kind`,
+  `event.category`, `event.type` and `event.outcome`. #684, #691, #692
 
 #### Improvements
 

From f3e2b80423c7fbc581b5dbaa6340732cc150583b Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 15:13:24 -0500
Subject: [PATCH 08/27] Introduce definitions pretty much as they are in the
 public comments doc.

---
 docs/field-details.asciidoc           |   4 +-
 docs/field-values.asciidoc            | 116 +++++++-----
 generated/ecs/ecs_flat.yml            | 254 ++++++++++++++++++-------
 generated/ecs/ecs_nested.yml          | 258 +++++++++++++++++++-------
 schemas/event.yml                     | 256 ++++++++++++++++++-------
 scripts/generators/asciidoc_fields.py |  36 ++--
 6 files changed, 648 insertions(+), 276 deletions(-)

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index 6f61bc5346..7092855a4c 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1316,7 +1316,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-failure, unknown, success
+failure, success, unknown
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-outcome,accepted values for event.outcome>>
@@ -1423,7 +1423,7 @@ type: keyword
 
 *Important*: The field value must be one of the following:
 
-access, allowed, audit, change, creation, deletion, denied, end, error, info, installation, protocol, start
+access, allowed, change, creation, deletion, denied, end, error, info, installation, protocol, start
 
 To learn more about when to use which value, visit the page
 <<ecs-accepted-values-event-type,accepted values for event.type>>
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 23db5c1a77..c5c0fa13b6 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -38,7 +38,7 @@ This gives information about what type of information the event contains, withou
 [[ecs-event-kind-alert]]
 ==== alert
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+`event.kind:alert` indicates an event that describes an alert. Alerts are often associated with detection rules. `event.kind:alert` is often populated for events coming from firewalls, intrusion detection systems, endpoint detection and response systems, etc. It is used to indicate that an alert was triggered.
 
 
 
@@ -47,7 +47,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-kind-event]]
 ==== event
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+It may sound a bit redundant, but `event.kind:event` is the most general and most common value of this field. It is used to represent events that indicate that something happened.
 
 
 
@@ -56,7 +56,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-kind-metric]]
 ==== metric
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Used to indicate that this event is a measurement taken at given point in time. Examples include CPU utilization, memory usage, or a vulnerability scan result. Events with `event.kind:metric` indicate that a measurement was taken.
 
 
 
@@ -65,7 +65,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-kind-state]]
 ==== state
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Similar to metric, except that the entity being measured does not provide a numeric metric value, but rather one of a fixed set of conditions or states. For example a periodic event reporting a "fin_wait" state of a TCP connection on a host might use `event.type:state`.
 
 
 
@@ -74,7 +74,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-kind-pipeline_error]]
 ==== pipeline_error
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+This value indicates that an error occurred during the ingestion of this event, and that event data may be missing, inconsistent, or incorrect. `event.kind:pipeline_error` is often associated with parsing errors.
 
 
 
@@ -83,7 +83,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-kind-signal]]
 ==== signal
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The signal value is used by Elastic Kibana apps, such as SIEM, for app-specific purposes. `event.kind:signal` is thus reserved and should not be used for the ingestion of events into Elasticsearch.
 
 
 
@@ -112,7 +112,7 @@ This contains high-level information about the contents of the event. It is more
 [[ecs-event-category-authentication]]
 ==== authentication
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows Event logs, ssh logs, etc. Visualize and analyze events in this category to look for unusual login activity, failed logins, etc.
 
 
 
@@ -125,85 +125,117 @@ allow, deny, info
 [[ecs-event-category-database]]
 ==== database
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The database category denotes events and metrics relating to a data storage and retrieval system. Note that use of this category is not limited to relational database systems. Examples include event logs from MS SQL, MySQL, Elasticsearch, MongoDB, etc. Use this category to visualize and analyze database activity such as accesses and changes.
 
 
 
+*Expected event types for category database:*
+
+access, change, info, error
+
 
 [float]
 [[ecs-event-category-driver]]
 ==== driver
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Having to do operating system device drivers and similar software entities such as Windows drivers, kernel extensions, kernel modules, etc. Use events and metrics in this category to visualize and analyze driver-related activity and status on hosts.
+
 
 
+*Expected event types for category driver:*
+
+change, end, info, start
 
 
 [float]
 [[ecs-event-category-file]]
 ==== file
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Relating to a set of information that has been created on, or has existed on a filesystem. Use this category of events to visualize and analyze the creation, access, permissions, transfers, and deletions of files. Events in this category can come from both host-based and network-based sources. An example source of a network-based detection of a file transfer would be the Zeek file.log.
+
+
 
+*Expected event types for category file:*
 
+change, creation, deletion, info
 
 
 [float]
 [[ecs-event-category-host]]
 ==== host
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Events and metrics about hosts. Usually higher-level information about host activity from an external perspective. Different than operating system in the sense that events are usually externally visible and independent from the OS. "host" events are not meant to capture events that are simply "happening on a host". Use this category to visualize and analyze inventories of hosts, starting and ending of hosts, etc.
+
 
 
+*Expected event types for category host:*
+
+access, change, end, info, start
 
 
 [float]
 [[ecs-event-category-intrusion_detection]]
 ==== intrusion_detection
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Relating to intrusion detections from IDS/IPS systems and functions, both network and host-based. Use this category to visualize and analyze intrusion detection alerts from systems such as Snort, Suricata, and Palo Alto threat detections.
 
 
 
+*Expected event types for category intrusion_detection:*
+
+info
+
 
 [float]
 [[ecs-event-category-malware]]
 ==== malware
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Malware detection events and alerts. Use this category to visualize and analyze malware detections from EDR/EPP systems such as Elastic Endpoint Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems and functions such as Palo Alto Networks threat and Wildfire logs.
+
 
 
+*Expected event types for category malware:*
+
+info
 
 
 [float]
 [[ecs-event-category-package]]
 ==== package
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Relating to software packages installed on hosts. Use this category to visualize and analyze inventory of software installed on various hosts, or to determine host vulnerability in the absence of vulnerability scan data.
+
+
 
+*Expected event types for category package:*
 
+access, change, deletion, info, installation, start
 
 
 [float]
 [[ecs-event-category-process]]
 ==== process
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Relating to the operation of software processes executing within operating systems on hosts. Use this category of events to visualize and analyze process starts, process parents, process relationships, etc.
 
 
 
 *Expected event types for category process:*
 
-start, info, end
+access, change, end, info, start
 
 
 [float]
 [[ecs-event-category-web]]
 ==== web
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Relating to web server access. Use this category to create a dashboard of web server/proxy activity from apache, IIS, nginx web servers, etc. Note: events from network observers such as Zeek http log may also be included in this category.
+
+
 
+*Expected event types for category web:*
 
+access, error, info
 
 
 [[ecs-accepted-values-event-type]]
@@ -215,7 +247,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 
 * <<ecs-event-type-access,access>>
 * <<ecs-event-type-allowed,allowed>>
-* <<ecs-event-type-audit,audit>>
 * <<ecs-event-type-change,change>>
 * <<ecs-event-type-creation,creation>>
 * <<ecs-event-type-deletion,deletion>>
@@ -231,7 +262,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-access]]
 ==== access
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The access event type is used for the subset of events within a category that indicate that something was accessed. Common examples include `event.category:database AND event.type:access`, or `event.category:file AND event.type:access`. Note for file access, include both directory listings and file opens in this subcategory. You can further distinguish access operations using the ECS `event.action` field.
 
 
 
@@ -240,16 +271,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-allowed]]
 ==== allowed
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-
-
-
-[float]
-[[ecs-event-type-audit]]
-==== audit
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The allow event type is used for the subset of events within a category that indicate that something was allowed. Common examples include `event.category:network AND event.type:allow` to indicate a network firewall event for which the firewall disposition was to allow the connection to complete. `event.category:network_flow AND event.type:allow` to indicate a network flow event that is also a network firewall event for which the firewall disposition was to allow the connection to complete.
 
 
 
@@ -258,7 +280,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-change]]
 ==== change
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The change event type is used for the subset of events within a category that indicate that something has changed. If semantics best describe an event as modified, then include them in this subcategory. Common examples include `event.category:registry AND event.type:change`, and `event.category:file AND event.type:change`. You can further distinguish change operations using the ECS `event.action` field.
 
 
 
@@ -267,7 +289,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-creation]]
 ==== creation
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The create event type is used for the subset of events within a category that indicate that something was created. A common example is `event.category:file AND event.type:create`.
 
 
 
@@ -276,7 +298,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-deletion]]
 ==== deletion
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The delete event type is used for the subset of events within a category that indicate that something was deleted. Common examples include `event.category:file AND event.type:delete`, and `event.category:iam_user AND event.type:delete`, to indicate that a user has been deleted from an Identity and Access Management system.
 
 
 
@@ -285,7 +307,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-denied]]
 ==== denied
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The deny event type is used for the subset of events within a category that indicate that something was disallowed, blocked or denied. Common examples include `event.category:network AND event.type:deny` to indicate a network firewall event for which the firewall disposition was to deny the connection to complete. `event.category:network_flow AND event.type:deny` to indicate a network flow event that is also a network firewall event for which the firewall disposition was to deny the connection to complete. Note that the `event.action` field can be used to further describe the deny action with user-supplied values such as "drop", "reject", "block", "redirect", etc.
 
 
 
@@ -294,7 +316,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-end]]
 ==== end
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The end event type is used for the subset of events within a category that indicate something has ended. Common examples include `event.category:process AND event.type:end`, and `event.category:network_flow AND event.type:end` to indicate a flow record event that is sent at the completion of the network flow.
 
 
 
@@ -303,7 +325,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-error]]
 ==== error
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The error event type is used for the subset of events within a category that indicate or describe an error. Common examples include `event.category:application AND event.type:error` and `event.category:database AND event.type:error`. Note that pipeline errors that occur during the event ingestion process should not use this `event.type` value. Instead, they should use the `event.kind:pipeline_error`.
 
 
 
@@ -312,7 +334,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-info]]
 ==== info
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The info event type is used for the subset of events within a category that indicate that they are purely informational, and don't report a state change, action. For example, an initial run of a file integrity monitoring system (FIM) where an agent reports all files under management would fall into the "info" subcategory. Similarly, a dump of all current running processes (as opposed to reporting that process start/end) would fall into the "info" subcategory. Additional common examples include `event.category:registry AND event.type:info`, and `event.category:intrusion_detection AND event.type:info`.
 
 
 
@@ -321,7 +343,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-installation]]
 ==== installation
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The install event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:install`.
 
 
 
@@ -330,7 +352,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-protocol]]
 ==== protocol
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The protocol event type is used for the subset of events within a category that indicate that they contain protocol details or analysis. Generally, network traffic and network flows that contain protocol details will fall into this subcategory. Common examples include `event.category:network AND event.type:protocol`, and `event.category:network_flow AND event.type:protocol`. Note for when the protocol subcategory is used, you can further distinguish protocols using the ECS `network.protocol` field.
 
 
 
@@ -339,7 +361,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 [[ecs-event-type-start]]
 ==== start
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+The start event type is used for the subset of events within a category that indicate something has started. A common example is `event.category:process AND event.type:start`.
 
 
 
@@ -354,32 +376,32 @@ If the event describes an action, this fields contains the outcome of that actio
 *Table of Contents*
 
 * <<ecs-event-outcome-failure,failure>>
-* <<ecs-event-outcome-unknown,unknown>>
 * <<ecs-event-outcome-success,success>>
+* <<ecs-event-outcome-unknown,unknown>>
 
 [float]
 [[ecs-event-outcome-failure]]
 ==== failure
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Indicates that this event describes a failed result. A common example is `event.category:file AND event.type:access AND event.outcome:failure` to indicate that a file access was attempted, but was not successful.
 
 
 
 
 [float]
-[[ecs-event-outcome-unknown]]
-==== unknown
+[[ecs-event-outcome-success]]
+==== success
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Indicates that this event describes a successful result.  A common example is `event.category:file AND event.type:create AND event.outcome:success` to indicate that a file was successfully created.
 
 
 
 
 [float]
-[[ecs-event-outcome-success]]
-==== success
+[[ecs-event-outcome-unknown]]
+==== unknown
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Indicates that this event describes only an attempt for which the result is unknown. For example, if the event contains information only about a request in an entity transaction that usually results in a response, populating `event.outcome:unknown` is appropriate.
 
 
 
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index c142c191c3..a19939d48f 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1372,8 +1372,11 @@ event.action:
   type: keyword
 event.category:
   accepted_values:
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Events in this category are related to the challenge and response
+      process in which credentials are supplied and verified to allow the creation
+      of a session. Common sources for these logs are Windows Event logs, ssh logs,
+      etc. Visualize and analyze events in this category to look for unusual login
+      activity, failed logins, etc.
 
       '
     expected_event_types:
@@ -1381,54 +1384,113 @@ event.category:
     - deny
     - info
     name: authentication
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The database category denotes events and metrics relating to a data
+      storage and retrieval system. Note that use of this category is not limited
+      to relational database systems. Examples include event logs from MS SQL, MySQL,
+      Elasticsearch, MongoDB, etc. Use this category to visualize and analyze database
+      activity such as accesses and changes.
 
       '
+    expected_event_types:
+    - access
+    - change
+    - info
+    - error
     name: database
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Having to do operating system device drivers and similar software
+      entities such as Windows drivers, kernel extensions, kernel modules, etc. Use
+      events and metrics in this category to visualize and analyze driver-related
+      activity and status on hosts.
 
       '
+    expected_event_types:
+    - change
+    - end
+    - info
+    - start
     name: driver
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Relating to a set of information that has been created on, or has
+      existed on a filesystem. Use this category of events to visualize and analyze
+      the creation, access, permissions, transfers, and deletions of files. Events
+      in this category can come from both host-based and network-based sources. An
+      example source of a network-based detection of a file transfer would be the
+      Zeek file.log.
 
       '
+    expected_event_types:
+    - change
+    - creation
+    - deletion
+    - info
     name: file
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Events and metrics about hosts. Usually higher-level information
+      about host activity from an external perspective. Different than operating system
+      in the sense that events are usually externally visible and independent from
+      the OS. "host" events are not meant to capture events that are simply "happening
+      on a host". Use this category to visualize and analyze inventories of hosts,
+      starting and ending of hosts, etc.
 
       '
+    expected_event_types:
+    - access
+    - change
+    - end
+    - info
+    - start
     name: host
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Relating to intrusion detections from IDS/IPS systems and functions,
+      both network and host-based. Use this category to visualize and analyze intrusion
+      detection alerts from systems such as Snort, Suricata, and Palo Alto threat
+      detections.
 
       '
+    expected_event_types:
+    - info
     name: intrusion_detection
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Malware detection events and alerts. Use this category to visualize
+      and analyze malware detections from EDR/EPP systems such as Elastic Endpoint
+      Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems
+      and functions such as Palo Alto Networks threat and Wildfire logs.
 
       '
+    expected_event_types:
+    - info
     name: malware
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Relating to software packages installed on hosts. Use this category
+      to visualize and analyze inventory of software installed on various hosts, or
+      to determine host vulnerability in the absence of vulnerability scan data.
 
       '
+    expected_event_types:
+    - access
+    - change
+    - deletion
+    - info
+    - installation
+    - start
     name: package
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Relating to the operation of software processes executing within
+      operating systems on hosts. Use this category of events to visualize and analyze
+      process starts, process parents, process relationships, etc.
 
       '
     expected_event_types:
-    - start
-    - info
+    - access
+    - change
     - end
+    - info
+    - start
     name: process
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Relating to web server access. Use this category to create a dashboard
+      of web server/proxy activity from apache, IIS, nginx web servers, etc. Note:
+      events from network observers such as Zeek http log may also be included in
+      this category.
 
       '
+    expected_event_types:
+    - access
+    - error
+    - info
     name: web
   dashed_name: event-category
   description: 'Event category.
@@ -1567,33 +1629,42 @@ event.ingested:
   type: date
 event.kind:
   accepted_values:
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: '`event.kind:alert` indicates an event that describes an alert. Alerts
+      are often associated with detection rules. `event.kind:alert` is often populated
+      for events coming from firewalls, intrusion detection systems, endpoint detection
+      and response systems, etc. It is used to indicate that an alert was triggered.
 
       '
     name: alert
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'It may sound a bit redundant, but `event.kind:event` is the most
+      general and most common value of this field. It is used to represent events
+      that indicate that something happened.
 
       '
     name: event
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Used to indicate that this event is a measurement taken at given
+      point in time. Examples include CPU utilization, memory usage, or a vulnerability
+      scan result. Events with `event.kind:metric` indicate that a measurement was
+      taken.
 
       '
     name: metric
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Similar to metric, except that the entity being measured does not
+      provide a numeric metric value, but rather one of a fixed set of conditions
+      or states. For example a periodic event reporting a "fin_wait" state of a TCP
+      connection on a host might use `event.type:state`.
 
       '
     name: state
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'This value indicates that an error occurred during the ingestion
+      of this event, and that event data may be missing, inconsistent, or incorrect.
+      `event.kind:pipeline_error` is often associated with parsing errors.
 
       '
     name: pipeline_error
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The signal value is used by Elastic Kibana apps, such as SIEM, for
+      app-specific purposes. `event.kind:signal` is thus reserved and should not be
+      used for the ingestion of events into Elasticsearch.
 
       '
     name: signal
@@ -1644,21 +1715,25 @@ event.original:
   type: keyword
 event.outcome:
   accepted_values:
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Indicates that this event describes a failed result. A common example
+      is `event.category:file AND event.type:access AND event.outcome:failure` to
+      indicate that a file access was attempted, but was not successful.
 
       '
     name: failure
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'Indicates that this event describes a successful result.  A common
+      example is `event.category:file AND event.type:create AND event.outcome:success`
+      to indicate that a file was successfully created.
 
       '
-    name: unknown
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+    name: success
+  - description: 'Indicates that this event describes only an attempt for which the
+      result is unknown. For example, if the event contains information only about
+      a request in an entity transaction that usually results in a response, populating
+      `event.outcome:unknown` is appropriate.
 
       '
-    name: success
+    name: unknown
   dashed_name: event-outcome
   description: 'The outcome of the event.
 
@@ -1771,68 +1846,105 @@ event.timezone:
   type: keyword
 event.type:
   accepted_values:
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The access event type is used for the subset of events within a
+      category that indicate that something was accessed. Common examples include
+      `event.category:database AND event.type:access`, or `event.category:file AND
+      event.type:access`. Note for file access, include both directory listings and
+      file opens in this subcategory. You can further distinguish access operations
+      using the ECS `event.action` field.
 
       '
     name: access
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The allow event type is used for the subset of events within a category
+      that indicate that something was allowed. Common examples include `event.category:network
+      AND event.type:allow` to indicate a network firewall event for which the firewall
+      disposition was to allow the connection to complete. `event.category:network_flow
+      AND event.type:allow` to indicate a network flow event that is also a network
+      firewall event for which the firewall disposition was to allow the connection
+      to complete.
 
       '
     name: allowed
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-      '
-    name: audit
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The change event type is used for the subset of events within a
+      category that indicate that something has changed. If semantics best describe
+      an event as modified, then include them in this subcategory. Common examples
+      include `event.category:registry AND event.type:change`, and `event.category:file
+      AND event.type:change`. You can further distinguish change operations using
+      the ECS `event.action` field.
 
       '
     name: change
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The create event type is used for the subset of events within a
+      category that indicate that something was created. A common example is `event.category:file
+      AND event.type:create`.
 
       '
     name: creation
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The delete event type is used for the subset of events within a
+      category that indicate that something was deleted. Common examples include `event.category:file
+      AND event.type:delete`, and `event.category:iam_user AND event.type:delete`,
+      to indicate that a user has been deleted from an Identity and Access Management
+      system.
 
       '
     name: deletion
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The deny event type is used for the subset of events within a category
+      that indicate that something was disallowed, blocked or denied. Common examples
+      include `event.category:network AND event.type:deny` to indicate a network firewall
+      event for which the firewall disposition was to deny the connection to complete.
+      `event.category:network_flow AND event.type:deny` to indicate a network flow
+      event that is also a network firewall event for which the firewall disposition
+      was to deny the connection to complete. Note that the `event.action` field can
+      be used to further describe the deny action with user-supplied values such as
+      "drop", "reject", "block", "redirect", etc.
 
       '
     name: denied
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The end event type is used for the subset of events within a category
+      that indicate something has ended. Common examples include `event.category:process
+      AND event.type:end`, and `event.category:network_flow AND event.type:end` to
+      indicate a flow record event that is sent at the completion of the network flow.
 
       '
     name: end
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The error event type is used for the subset of events within a category
+      that indicate or describe an error. Common examples include `event.category:application
+      AND event.type:error` and `event.category:database AND event.type:error`. Note
+      that pipeline errors that occur during the event ingestion process should not
+      use this `event.type` value. Instead, they should use the `event.kind:pipeline_error`.
 
       '
     name: error
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The info event type is used for the subset of events within a category
+      that indicate that they are purely informational, and don''t report a state
+      change, action. For example, an initial run of a file integrity monitoring system
+      (FIM) where an agent reports all files under management would fall into the
+      "info" subcategory. Similarly, a dump of all current running processes (as opposed
+      to reporting that process start/end) would fall into the "info" subcategory.
+      Additional common examples include `event.category:registry AND event.type:info`,
+      and `event.category:intrusion_detection AND event.type:info`.
 
       '
     name: info
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The install event type is used for the subset of events within a
+      category that indicate that something was installed. A common example is `event.category:package`
+      AND `event.type:install`.
 
       '
     name: installation
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The protocol event type is used for the subset of events within
+      a category that indicate that they contain protocol details or analysis. Generally,
+      network traffic and network flows that contain protocol details will fall into
+      this subcategory. Common examples include `event.category:network AND event.type:protocol`,
+      and `event.category:network_flow AND event.type:protocol`. Note for when the
+      protocol subcategory is used, you can further distinguish protocols using the
+      ECS `network.protocol` field.
 
       '
     name: protocol
-  - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-      eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  - description: 'The start event type is used for the subset of events within a category
+      that indicate something has started. A common example is `event.category:process
+      AND event.type:start`.
 
       '
     name: start
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index 121704b29a..6767c5fa6e 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1586,8 +1586,11 @@ event:
       type: keyword
     category:
       accepted_values:
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Events in this category are related to the challenge and response
+          process in which credentials are supplied and verified to allow the creation
+          of a session. Common sources for these logs are Windows Event logs, ssh
+          logs, etc. Visualize and analyze events in this category to look for unusual
+          login activity, failed logins, etc.
 
           '
         expected_event_types:
@@ -1595,54 +1598,114 @@ event:
         - deny
         - info
         name: authentication
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The database category denotes events and metrics relating to
+          a data storage and retrieval system. Note that use of this category is not
+          limited to relational database systems. Examples include event logs from
+          MS SQL, MySQL, Elasticsearch, MongoDB, etc. Use this category to visualize
+          and analyze database activity such as accesses and changes.
 
           '
+        expected_event_types:
+        - access
+        - change
+        - info
+        - error
         name: database
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Having to do operating system device drivers and similar software
+          entities such as Windows drivers, kernel extensions, kernel modules, etc.
+          Use events and metrics in this category to visualize and analyze driver-related
+          activity and status on hosts.
 
           '
+        expected_event_types:
+        - change
+        - end
+        - info
+        - start
         name: driver
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Relating to a set of information that has been created on, or
+          has existed on a filesystem. Use this category of events to visualize and
+          analyze the creation, access, permissions, transfers, and deletions of files.
+          Events in this category can come from both host-based and network-based
+          sources. An example source of a network-based detection of a file transfer
+          would be the Zeek file.log.
 
           '
+        expected_event_types:
+        - change
+        - creation
+        - deletion
+        - info
         name: file
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Events and metrics about hosts. Usually higher-level information
+          about host activity from an external perspective. Different than operating
+          system in the sense that events are usually externally visible and independent
+          from the OS. "host" events are not meant to capture events that are simply
+          "happening on a host". Use this category to visualize and analyze inventories
+          of hosts, starting and ending of hosts, etc.
 
           '
+        expected_event_types:
+        - access
+        - change
+        - end
+        - info
+        - start
         name: host
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Relating to intrusion detections from IDS/IPS systems and functions,
+          both network and host-based. Use this category to visualize and analyze
+          intrusion detection alerts from systems such as Snort, Suricata, and Palo
+          Alto threat detections.
 
           '
+        expected_event_types:
+        - info
         name: intrusion_detection
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Malware detection events and alerts. Use this category to visualize
+          and analyze malware detections from EDR/EPP systems such as Elastic Endpoint
+          Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS
+          systems and functions such as Palo Alto Networks threat and Wildfire logs.
 
           '
+        expected_event_types:
+        - info
         name: malware
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Relating to software packages installed on hosts. Use this category
+          to visualize and analyze inventory of software installed on various hosts,
+          or to determine host vulnerability in the absence of vulnerability scan
+          data.
 
           '
+        expected_event_types:
+        - access
+        - change
+        - deletion
+        - info
+        - installation
+        - start
         name: package
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Relating to the operation of software processes executing within
+          operating systems on hosts. Use this category of events to visualize and
+          analyze process starts, process parents, process relationships, etc.
 
           '
         expected_event_types:
-        - start
-        - info
+        - access
+        - change
         - end
+        - info
+        - start
         name: process
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Relating to web server access. Use this category to create a
+          dashboard of web server/proxy activity from apache, IIS, nginx web servers,
+          etc. Note: events from network observers such as Zeek http log may also
+          be included in this category.
 
           '
+        expected_event_types:
+        - access
+        - error
+        - info
         name: web
       dashed_name: event-category
       description: 'Event category.
@@ -1782,33 +1845,43 @@ event:
       type: date
     kind:
       accepted_values:
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: '`event.kind:alert` indicates an event that describes an alert.
+          Alerts are often associated with detection rules. `event.kind:alert` is
+          often populated for events coming from firewalls, intrusion detection systems,
+          endpoint detection and response systems, etc. It is used to indicate that
+          an alert was triggered.
 
           '
         name: alert
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'It may sound a bit redundant, but `event.kind:event` is the
+          most general and most common value of this field. It is used to represent
+          events that indicate that something happened.
 
           '
         name: event
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Used to indicate that this event is a measurement taken at given
+          point in time. Examples include CPU utilization, memory usage, or a vulnerability
+          scan result. Events with `event.kind:metric` indicate that a measurement
+          was taken.
 
           '
         name: metric
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Similar to metric, except that the entity being measured does
+          not provide a numeric metric value, but rather one of a fixed set of conditions
+          or states. For example a periodic event reporting a "fin_wait" state of
+          a TCP connection on a host might use `event.type:state`.
 
           '
         name: state
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'This value indicates that an error occurred during the ingestion
+          of this event, and that event data may be missing, inconsistent, or incorrect.
+          `event.kind:pipeline_error` is often associated with parsing errors.
 
           '
         name: pipeline_error
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The signal value is used by Elastic Kibana apps, such as SIEM,
+          for app-specific purposes. `event.kind:signal` is thus reserved and should
+          not be used for the ingestion of events into Elasticsearch.
 
           '
         name: signal
@@ -1859,21 +1932,25 @@ event:
       type: keyword
     outcome:
       accepted_values:
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Indicates that this event describes a failed result. A common
+          example is `event.category:file AND event.type:access AND event.outcome:failure`
+          to indicate that a file access was attempted, but was not successful.
 
           '
         name: failure
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'Indicates that this event describes a successful result.  A
+          common example is `event.category:file AND event.type:create AND event.outcome:success`
+          to indicate that a file was successfully created.
 
           '
-        name: unknown
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+        name: success
+      - description: 'Indicates that this event describes only an attempt for which
+          the result is unknown. For example, if the event contains information only
+          about a request in an entity transaction that usually results in a response,
+          populating `event.outcome:unknown` is appropriate.
 
           '
-        name: success
+        name: unknown
       dashed_name: event-outcome
       description: 'The outcome of the event.
 
@@ -1988,68 +2065,107 @@ event:
       type: keyword
     type:
       accepted_values:
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The access event type is used for the subset of events within
+          a category that indicate that something was accessed. Common examples include
+          `event.category:database AND event.type:access`, or `event.category:file
+          AND event.type:access`. Note for file access, include both directory listings
+          and file opens in this subcategory. You can further distinguish access operations
+          using the ECS `event.action` field.
 
           '
         name: access
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The allow event type is used for the subset of events within
+          a category that indicate that something was allowed. Common examples include
+          `event.category:network AND event.type:allow` to indicate a network firewall
+          event for which the firewall disposition was to allow the connection to
+          complete. `event.category:network_flow AND event.type:allow` to indicate
+          a network flow event that is also a network firewall event for which the
+          firewall disposition was to allow the connection to complete.
 
           '
         name: allowed
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
-          '
-        name: audit
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The change event type is used for the subset of events within
+          a category that indicate that something has changed. If semantics best describe
+          an event as modified, then include them in this subcategory. Common examples
+          include `event.category:registry AND event.type:change`, and `event.category:file
+          AND event.type:change`. You can further distinguish change operations using
+          the ECS `event.action` field.
 
           '
         name: change
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The create event type is used for the subset of events within
+          a category that indicate that something was created. A common example is
+          `event.category:file AND event.type:create`.
 
           '
         name: creation
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The delete event type is used for the subset of events within
+          a category that indicate that something was deleted. Common examples include
+          `event.category:file AND event.type:delete`, and `event.category:iam_user
+          AND event.type:delete`, to indicate that a user has been deleted from an
+          Identity and Access Management system.
 
           '
         name: deletion
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The deny event type is used for the subset of events within
+          a category that indicate that something was disallowed, blocked or denied.
+          Common examples include `event.category:network AND event.type:deny` to
+          indicate a network firewall event for which the firewall disposition was
+          to deny the connection to complete. `event.category:network_flow AND event.type:deny`
+          to indicate a network flow event that is also a network firewall event for
+          which the firewall disposition was to deny the connection to complete. Note
+          that the `event.action` field can be used to further describe the deny action
+          with user-supplied values such as "drop", "reject", "block", "redirect",
+          etc.
 
           '
         name: denied
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The end event type is used for the subset of events within a
+          category that indicate something has ended. Common examples include `event.category:process
+          AND event.type:end`, and `event.category:network_flow AND event.type:end`
+          to indicate a flow record event that is sent at the completion of the network
+          flow.
 
           '
         name: end
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The error event type is used for the subset of events within
+          a category that indicate or describe an error. Common examples include `event.category:application
+          AND event.type:error` and `event.category:database AND event.type:error`.
+          Note that pipeline errors that occur during the event ingestion process
+          should not use this `event.type` value. Instead, they should use the `event.kind:pipeline_error`.
 
           '
         name: error
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The info event type is used for the subset of events within
+          a category that indicate that they are purely informational, and don''t
+          report a state change, action. For example, an initial run of a file integrity
+          monitoring system (FIM) where an agent reports all files under management
+          would fall into the "info" subcategory. Similarly, a dump of all current
+          running processes (as opposed to reporting that process start/end) would
+          fall into the "info" subcategory. Additional common examples include `event.category:registry
+          AND event.type:info`, and `event.category:intrusion_detection AND event.type:info`.
 
           '
         name: info
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The install event type is used for the subset of events within
+          a category that indicate that something was installed. A common example
+          is `event.category:package` AND `event.type:install`.
 
           '
         name: installation
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The protocol event type is used for the subset of events within
+          a category that indicate that they contain protocol details or analysis.
+          Generally, network traffic and network flows that contain protocol details
+          will fall into this subcategory. Common examples include `event.category:network
+          AND event.type:protocol`, and `event.category:network_flow AND event.type:protocol`.
+          Note for when the protocol subcategory is used, you can further distinguish
+          protocols using the ECS `network.protocol` field.
 
           '
         name: protocol
-      - description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
-          do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      - description: 'The start event type is used for the subset of events within
+          a category that indicate something has started. A common example is `event.category:process
+          AND event.type:start`.
 
           '
         name: start
diff --git a/schemas/event.yml b/schemas/event.yml
index ac06ebaf97..5d6e7f2a5c 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -50,28 +50,37 @@
       accepted_values:
         - name: alert
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            `event.kind:alert` indicates an event that describes an alert.
+            Alerts are often associated with detection rules. `event.kind:alert`
+            is often populated for events coming from firewalls, intrusion detection
+            systems, endpoint detection and response systems, etc.
+            It is used to indicate that an alert was triggered.
         - name: event
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            It may sound a bit redundant, but `event.kind:event` is the most general
+            and most common value of this field. It is used to represent events that
+            indicate that something happened.
         - name: metric
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Used to indicate that this event is a measurement taken at given point in time.
+            Examples include CPU utilization, memory usage, or a vulnerability scan result.
+            Events with `event.kind:metric` indicate that a measurement was taken.
         - name: state
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Similar to metric, except that the entity being measured does not
+            provide a numeric metric value, but rather one of a fixed set of conditions or states.
+            For example a periodic event reporting a "fin_wait" state of a TCP connection
+            on a host might use `event.type:state`.
         - name: pipeline_error
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            This value indicates that an error occurred during the ingestion of this event,
+            and that event data may be missing, inconsistent, or incorrect.
+            `event.kind:pipeline_error` is often associated with parsing errors.
         - name: signal
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The signal value is used by Elastic Kibana apps, such as SIEM, for app-specific purposes.
+            `event.kind:signal` is thus reserved and should not be used for the ingestion
+            of events into Elasticsearch.
 
     - name: category
       level: core
@@ -87,52 +96,111 @@
       accepted_values:
         - name: authentication
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Events in this category are related to the challenge and response process
+            in which credentials are supplied and verified to allow the creation of a session.
+            Common sources for these logs are Windows Event logs, ssh logs, etc.
+            Visualize and analyze events in this category to look for unusual login activity,
+            failed logins, etc.
           expected_event_types:
             - allow
             - deny
             - info
         - name: database
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The database category denotes events and metrics relating to a data storage
+            and retrieval system. Note that use of this category is not limited to
+            relational database systems. Examples include event logs from MS SQL, MySQL,
+            Elasticsearch, MongoDB, etc. Use this category to visualize and analyze
+            database activity such as accesses and changes.
+          expected_event_types:
+            - access
+            - change
+            - info
+            - error
         - name: driver
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Having to do operating system device drivers and similar software entities
+            such as Windows drivers, kernel extensions, kernel modules, etc.
+            Use events and metrics in this category to visualize and analyze driver-related
+            activity and status on hosts.
+          expected_event_types:
+            - change
+            - end
+            - info
+            - start
         - name: file
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Relating to a set of information that has been created on, or has existed on a filesystem.
+            Use this category of events to visualize and analyze the creation, access,
+            permissions, transfers, and deletions of files. Events in this category can come
+            from both host-based and network-based sources. An example source of a network-based
+            detection of a file transfer would be the Zeek file.log.
+          expected_event_types:
+            - change
+            - creation
+            - deletion
+            - info
         - name: host
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Events and metrics about hosts. Usually higher-level information about host
+            activity from an external perspective. Different than operating system
+            in the sense that events are usually externally visible and independent from the OS.
+            "host" events are not meant to capture events that are simply "happening on a host".
+            Use this category to visualize and analyze inventories of hosts,
+            starting and ending of hosts, etc.
+          expected_event_types:
+            - access
+            - change
+            - end
+            - info
+            - start
         - name: intrusion_detection
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Relating to intrusion detections from IDS/IPS systems and functions,
+            both network and host-based. Use this category to visualize and analyze
+            intrusion detection alerts from systems such as Snort, Suricata,
+            and Palo Alto threat detections.
+          expected_event_types:
+            - info
         - name: malware
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Malware detection events and alerts. Use this category to visualize and analyze
+            malware detections from EDR/EPP systems such as Elastic Endpoint Security,
+            Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems and
+            functions such as Palo Alto Networks threat and Wildfire logs.
+          expected_event_types:
+            - info
         - name: package
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Relating to software packages installed on hosts. Use this category to
+            visualize and analyze inventory of software installed on various hosts,
+            or to determine host vulnerability in the absence of vulnerability scan data.
+          expected_event_types:
+            - access
+            - change
+            - deletion
+            - info
+            - installation
+            - start
         - name: process
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Relating to the operation of software processes executing within operating systems on hosts. Use this category of events to visualize and analyze process starts, process parents, process relationships, etc.
           expected_event_types:
-            - start
-            - info
+            - access
+            - change
             - end
+            - info
+            - start
         - name: web
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Relating to web server access. Use this category to create a dashboard of
+            web server/proxy activity from apache, IIS, nginx web servers, etc.
+            Note: events from network observers such as Zeek http log may also be included
+            in this category.
+          expected_event_types:
+            - access
+            - error
+            - info
 
     - name: action
       level: core
@@ -160,16 +228,20 @@
       accepted_values:
         - name: failure
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: unknown
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Indicates that this event describes a failed result. A common example is
+            `event.category:file AND event.type:access AND event.outcome:failure`
+            to indicate that a file access was attempted, but was not successful.
         - name: success
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            Indicates that this event describes a successful result.  A common example is
+            `event.category:file AND event.type:create AND event.outcome:success`
+            to indicate that a file was successfully created.
+        - name: unknown
+          description: >
+            Indicates that this event describes only an attempt for which the result
+            is unknown. For example, if the event contains information only about a
+            request in an entity transaction that usually results in a response,
+            populating `event.outcome:unknown` is appropriate.
 
     - name: type
       level: core
@@ -182,56 +254,100 @@
       accepted_values:
         - name: access
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The access event type is used for the subset of events within a category
+            that indicate that something was accessed.
+            Common examples include `event.category:database AND event.type:access`,
+            or `event.category:file AND event.type:access`.
+            Note for file access, include both directory listings and file opens in this subcategory.
+            You can further distinguish access operations using the ECS `event.action` field.
         - name: allowed
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
-        - name: audit
-          description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The allow event type is used for the subset of events within a category
+            that indicate that something was allowed.
+            Common examples include `event.category:network AND event.type:allow`
+            to indicate a network firewall event for which the firewall disposition
+            was to allow the connection to complete.
+            `event.category:network_flow AND event.type:allow` to indicate a network flow event
+            that is also a network firewall event for which the firewall disposition
+            was to allow the connection to complete.
         - name: change
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The change event type is used for the subset of events within a category
+            that indicate that something has changed. If semantics best describe an
+            event as modified, then include them in this subcategory.
+            Common examples include `event.category:registry AND event.type:change`,
+            and `event.category:file AND event.type:change`.
+            You can further distinguish change operations using the ECS `event.action` field.
         - name: creation
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The create event type is used for the subset of events within a category
+            that indicate that something was created.
+            A common example is `event.category:file AND event.type:create`.
         - name: deletion
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The delete event type is used for the subset of events within a category
+            that indicate that something was deleted.
+            Common examples include `event.category:file AND event.type:delete`,
+            and `event.category:iam_user AND event.type:delete`,
+            to indicate that a user has been deleted from an Identity and Access Management system.
         - name: denied
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The deny event type is used for the subset of events within a category
+            that indicate that something was disallowed, blocked or denied.
+            Common examples include `event.category:network AND event.type:deny`
+            to indicate a network firewall event for which the firewall disposition
+            was to deny the connection to complete.
+            `event.category:network_flow AND event.type:deny` to indicate a network flow
+            event that is also a network firewall event for which the firewall disposition
+            was to deny the connection to complete.
+            Note that the `event.action` field can be used to further describe the
+            deny action with user-supplied values such as "drop", "reject", "block", "redirect", etc.
         - name: end
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The end event type is used for the subset of events within a category
+            that indicate something has ended.
+            Common examples include `event.category:process AND event.type:end`,
+            and `event.category:network_flow AND event.type:end`
+            to indicate a flow record event that is sent at the completion of the network flow.
         - name: error
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The error event type is used for the subset of events within a category
+            that indicate or describe an error.
+            Common examples include `event.category:application AND event.type:error`
+            and `event.category:database AND event.type:error`.
+            Note that pipeline errors that occur during the event ingestion process
+            should not use this `event.type` value.
+            Instead, they should use the `event.kind:pipeline_error`.
         - name: info
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The info event type is used for the subset of events within a category
+            that indicate that they are purely informational, and don't report a state change, action.
+            For example, an initial run of a file integrity monitoring system (FIM)
+            where an agent reports all files under management would fall into the "info" subcategory.
+            Similarly, a dump of all current running processes (as opposed to reporting that process start/end)
+            would fall into the "info" subcategory.
+            Additional common examples include `event.category:registry AND event.type:info`,
+            and `event.category:intrusion_detection AND event.type:info`.
         - name: installation
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The install event type is used for the subset of events within a category
+            that indicate that something was installed.
+            A common example is `event.category:package` AND `event.type:install`.
         - name: protocol
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The protocol event type is used for the subset of events within a category
+            that indicate that they contain protocol details or analysis.
+            Generally, network traffic and network flows that contain protocol
+            details will fall into this subcategory.
+            Common examples include `event.category:network AND event.type:protocol`,
+            and `event.category:network_flow AND event.type:protocol`.
+            Note for when the protocol subcategory is used, you can further distinguish
+            protocols using the ECS `network.protocol` field.
         - name: start
           description: >
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
-            incididunt ut labore et dolore magna aliqua.
+            The start event type is used for the subset of events within a category
+            that indicate something has started. A common example is
+            `event.category:process AND event.type:start`.
 
     - name: module
       level: core
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index c665acb755..974b85bac9 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -339,21 +339,27 @@ def render_field_values_page(field):
     # Each accepted value
     body = ''
     toc = ''
-    for value_details in field['accepted_values']:
-        toc += "* <<ecs-{field_dashed_name}-{value_name},{value_name}>>\n".format(
-            field_dashed_name=field['dashed_name'],
-            value_name=value_details['name']
-        )
-        if 'expected_event_types' in value_details:
-            additional_details = render_expected_event_types(value_details)
-        else:
-            additional_details = ''
-        body += field_value_template().format(
-            field_dashed_name=field['dashed_name'],
-            value_name=value_details['name'],
-            value_description=value_details['description'],
-            additional_details=additional_details
-        )
+    try:
+        for value_details in field['accepted_values']:
+            toc += "* <<ecs-{field_dashed_name}-{value_name},{value_name}>>\n".format(
+                field_dashed_name=field['dashed_name'],
+                value_name=value_details['name']
+            )
+            if 'expected_event_types' in value_details:
+                additional_details = render_expected_event_types(value_details)
+            else:
+                additional_details = ''
+            body += field_value_template().format(
+                field_dashed_name=field['dashed_name'],
+                value_name=value_details['name'],
+                value_description=value_details['description'],
+                additional_details=additional_details
+            )
+    except UnicodeEncodeError:
+        print("Problem with field {}, field value:".format(field['flat_name']))
+        # print(heading + toc + body)
+        print(value_details)
+        raise
     return heading + toc + body
 
 

From 91aec05e512e1314e2beb98a78329dc6bc850175 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 15:39:12 -0500
Subject: [PATCH 09/27] Replace 'accepted' with 'allowed'

---
 docs/field-details.asciidoc           |  8 +++----
 docs/field-values.asciidoc            | 24 ++++++++++-----------
 generated/beats/fields.ecs.yml        |  2 +-
 generated/csv/fields.csv              |  2 +-
 generated/ecs/ecs_flat.yml            | 10 ++++-----
 generated/ecs/ecs_nested.yml          | 10 ++++-----
 schemas/event.yml                     | 10 ++++-----
 scripts/generators/asciidoc_fields.py | 30 +++++++++++++--------------
 8 files changed, 48 insertions(+), 48 deletions(-)

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index 7092855a4c..4dc2ec5f3d 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1147,7 +1147,7 @@ type: keyword
 authentication, database, driver, file, host, intrusion_detection, malware, package, process, web
 
 To learn more about when to use which value, visit the page
-<<ecs-accepted-values-event-category,accepted values for event.category>>
+<<ecs-allowed-values-event-category,allowed values for event.category>>
 
 
 | core
@@ -1273,7 +1273,7 @@ type: keyword
 alert, event, metric, state, pipeline_error, signal
 
 To learn more about when to use which value, visit the page
-<<ecs-accepted-values-event-kind,accepted values for event.kind>>
+<<ecs-allowed-values-event-kind,allowed values for event.kind>>
 
 
 | extended
@@ -1319,7 +1319,7 @@ type: keyword
 failure, success, unknown
 
 To learn more about when to use which value, visit the page
-<<ecs-accepted-values-event-outcome,accepted values for event.outcome>>
+<<ecs-allowed-values-event-outcome,allowed values for event.outcome>>
 
 
 | extended
@@ -1426,7 +1426,7 @@ type: keyword
 access, allowed, change, creation, deletion, denied, end, error, info, installation, protocol, start
 
 To learn more about when to use which value, visit the page
-<<ecs-accepted-values-event-type,accepted values for event.type>>
+<<ecs-allowed-values-event-type,allowed values for event.type>>
 
 
 | core
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index c5c0fa13b6..e56d3d39a4 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -12,14 +12,14 @@ ECS defines four Categorization Fields for this purpose, each of which falls und
 [[ecs-category-fields]]
 === Categorization Fields
 
-* <<ecs-accepted-values-event-kind,event.kind>>
-* <<ecs-accepted-values-event-category,event.category>>
-* <<ecs-accepted-values-event-type,event.type>>
-* <<ecs-accepted-values-event-outcome,event.outcome>>
+* <<ecs-allowed-values-event-kind,event.kind>>
+* <<ecs-allowed-values-event-category,event.category>>
+* <<ecs-allowed-values-event-type,event.type>>
+* <<ecs-allowed-values-event-outcome,event.outcome>>
 
 
-[[ecs-accepted-values-event-kind]]
-=== Accepted Values for event.kind
+[[ecs-allowed-values-event-kind]]
+=== Allowed Values for event.kind
 
 The kind of the event.
 
@@ -88,8 +88,8 @@ The signal value is used by Elastic Kibana apps, such as SIEM, for app-specific
 
 
 
-[[ecs-accepted-values-event-category]]
-=== Accepted Values for event.category
+[[ecs-allowed-values-event-category]]
+=== Allowed Values for event.category
 
 Event category.
 
@@ -238,8 +238,8 @@ Relating to web server access. Use this category to create a dashboard of web se
 access, error, info
 
 
-[[ecs-accepted-values-event-type]]
-=== Accepted Values for event.type
+[[ecs-allowed-values-event-type]]
+=== Allowed Values for event.type
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
@@ -366,8 +366,8 @@ The start event type is used for the subset of events within a category that ind
 
 
 
-[[ecs-accepted-values-event-outcome]]
-=== Accepted Values for event.outcome
+[[ecs-allowed-values-event-outcome]]
+=== Allowed Values for event.outcome
 
 The outcome of the event.
 
diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml
index 8c39f9a22d..09b0a65044 100644
--- a/generated/beats/fields.ecs.yml
+++ b/generated/beats/fields.ecs.yml
@@ -950,7 +950,7 @@
         This contains high-level information about the contents of the event. It is
         more generic than `event.action`, in the sense that typically a category contains
         multiple actions.'
-      example: user-management
+      example: authentication
     - name: code
       level: extended
       type: keyword
diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv
index 310499bde5..d90632b38e 100644
--- a/generated/csv/fields.csv
+++ b/generated/csv/fields.csv
@@ -116,7 +116,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,false,error,error.stack_trace.text,text,extended,,The stack trace of this error in plain text.
 1.4.0-dev,true,error,error.type,keyword,extended,java.lang.NullPointerException,"The type of the error, for example the class name of the exception."
 1.4.0-dev,true,event,event.action,keyword,core,user-password-change,The action captured by the event.
-1.4.0-dev,true,event,event.category,keyword,core,user-management,Event category.
+1.4.0-dev,true,event,event.category,keyword,core,authentication,Event category.
 1.4.0-dev,true,event,event.code,keyword,extended,4648,Identification code for this event.
 1.4.0-dev,true,event,event.created,date,core,2016-05-23 08:05:34.857000,Time when the event was first read by an agent or by your pipeline.
 1.4.0-dev,true,event,event.dataset,keyword,core,apache.access,Name of the dataset.
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index a19939d48f..15492a75fc 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1371,7 +1371,7 @@ event.action:
   short: The action captured by the event.
   type: keyword
 event.category:
-  accepted_values:
+  allowed_values:
   - description: 'Events in this category are related to the challenge and response
       process in which credentials are supplied and verified to allow the creation
       of a session. Common sources for these logs are Windows Event logs, ssh logs,
@@ -1498,7 +1498,7 @@ event.category:
     This contains high-level information about the contents of the event. It is more
     generic than `event.action`, in the sense that typically a category contains multiple
     actions.'
-  example: user-management
+  example: authentication
   flat_name: event.category
   ignore_above: 1024
   level: core
@@ -1628,7 +1628,7 @@ event.ingested:
   short: Timestamp when an event arrived in the central data store.
   type: date
 event.kind:
-  accepted_values:
+  allowed_values:
   - description: '`event.kind:alert` indicates an event that describes an alert. Alerts
       are often associated with detection rules. `event.kind:alert` is often populated
       for events coming from firewalls, intrusion detection systems, endpoint detection
@@ -1714,7 +1714,7 @@ event.original:
   short: Raw text message of entire event.
   type: keyword
 event.outcome:
-  accepted_values:
+  allowed_values:
   - description: 'Indicates that this event describes a failed result. A common example
       is `event.category:file AND event.type:access AND event.outcome:failure` to
       indicate that a file access was attempted, but was not successful.
@@ -1845,7 +1845,7 @@ event.timezone:
   short: Event time zone.
   type: keyword
 event.type:
-  accepted_values:
+  allowed_values:
   - description: 'The access event type is used for the subset of events within a
       category that indicate that something was accessed. Common examples include
       `event.category:database AND event.type:access`, or `event.category:file AND
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index 6767c5fa6e..43529e6625 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1585,7 +1585,7 @@ event:
       short: The action captured by the event.
       type: keyword
     category:
-      accepted_values:
+      allowed_values:
       - description: 'Events in this category are related to the challenge and response
           process in which credentials are supplied and verified to allow the creation
           of a session. Common sources for these logs are Windows Event logs, ssh
@@ -1713,7 +1713,7 @@ event:
         This contains high-level information about the contents of the event. It is
         more generic than `event.action`, in the sense that typically a category contains
         multiple actions.'
-      example: user-management
+      example: authentication
       flat_name: event.category
       ignore_above: 1024
       level: core
@@ -1844,7 +1844,7 @@ event:
       short: Timestamp when an event arrived in the central data store.
       type: date
     kind:
-      accepted_values:
+      allowed_values:
       - description: '`event.kind:alert` indicates an event that describes an alert.
           Alerts are often associated with detection rules. `event.kind:alert` is
           often populated for events coming from firewalls, intrusion detection systems,
@@ -1931,7 +1931,7 @@ event:
       short: Raw text message of entire event.
       type: keyword
     outcome:
-      accepted_values:
+      allowed_values:
       - description: 'Indicates that this event describes a failed result. A common
           example is `event.category:file AND event.type:access AND event.outcome:failure`
           to indicate that a file access was attempted, but was not successful.
@@ -2064,7 +2064,7 @@ event:
       short: Event time zone.
       type: keyword
     type:
-      accepted_values:
+      allowed_values:
       - description: 'The access event type is used for the subset of events within
           a category that indicate that something was accessed. Common examples include
           `event.category:database AND event.type:access`, or `event.category:file
diff --git a/schemas/event.yml b/schemas/event.yml
index 5d6e7f2a5c..5b1dc64580 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -47,7 +47,7 @@
         This gives information about what type of information the event
         contains, without being specific to the contents of the event.
       example: event
-      accepted_values:
+      allowed_values:
         - name: alert
           description: >
             `event.kind:alert` indicates an event that describes an alert.
@@ -92,8 +92,8 @@
         This contains high-level information about the contents of the event. It
         is more generic than `event.action`, in the sense that typically a
         category contains multiple actions.
-      example: user-management
-      accepted_values:
+      example: authentication
+      allowed_values:
         - name: authentication
           description: >
             Events in this category are related to the challenge and response process
@@ -225,7 +225,7 @@
         that action.
       example: success
 
-      accepted_values:
+      allowed_values:
         - name: failure
           description: >
             Indicates that this event describes a failed result. A common example is
@@ -251,7 +251,7 @@
         Lorem ipsum dolor sit amet, consectetur adipiscing elit,
         sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-      accepted_values:
+      allowed_values:
         - name: access
           description: >
             The access event type is used for the subset of events within a category
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 974b85bac9..2605c7252d 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -74,10 +74,10 @@ def render_asciidoc_paragraphs(string):
     return string.replace("\n", "\n\n")
 
 
-def render_field_accepted_values(field):
-    if not 'accepted_values' in field:
+def render_field_allowed_values(field):
+    if not 'allowed_values' in field:
         return ''
-    allowed_values = ', '.join(ecs_helpers.list_extract_keys(field['accepted_values'], 'name'))
+    allowed_values = ', '.join(ecs_helpers.list_extract_keys(field['allowed_values'], 'name'))
     return field_acceptable_value_names().format(
         allowed_values=allowed_values,
         field_flat_name=field['flat_name'],
@@ -87,8 +87,8 @@ def render_field_accepted_values(field):
 
 def render_field_details_row(field):
     example = ''
-    if 'accepted_values' in field:
-        example = render_field_accepted_values(field)
+    if 'allowed_values' in field:
+        example = render_field_allowed_values(field)
     elif 'example' in field:
         example = "example: `{}`".format(str(field['example']))
 
@@ -253,7 +253,7 @@ def field_acceptable_value_names():
 {allowed_values}
 
 To learn more about when to use which value, visit the page
-<<ecs-accepted-values-{field_dashed_name},accepted values for {field_flat_name}>>
+<<ecs-allowed-values-{field_dashed_name},allowed values for {field_flat_name}>>
 '''
 
 
@@ -294,7 +294,7 @@ def nestings_row():
 '''
 
 
-# Accepted values section
+# Allowed values section
 
 
 def page_field_values(ecs_flat):
@@ -320,10 +320,10 @@ def values_section_header():
 [[ecs-category-fields]]
 === Categorization Fields
 
-* <<ecs-accepted-values-event-kind,event.kind>>
-* <<ecs-accepted-values-event-category,event.category>>
-* <<ecs-accepted-values-event-type,event.type>>
-* <<ecs-accepted-values-event-outcome,event.outcome>>
+* <<ecs-allowed-values-event-kind,event.kind>>
+* <<ecs-allowed-values-event-category,event.category>>
+* <<ecs-allowed-values-event-type,event.type>>
+* <<ecs-allowed-values-event-outcome,event.outcome>>
 
 '''
 
@@ -336,11 +336,11 @@ def render_field_values_page(field):
         field_description=render_asciidoc_paragraphs(field['description']),
     )
 
-    # Each accepted value
+    # Each allowed value
     body = ''
     toc = ''
     try:
-        for value_details in field['accepted_values']:
+        for value_details in field['allowed_values']:
             toc += "* <<ecs-{field_dashed_name}-{value_name},{value_name}>>\n".format(
                 field_dashed_name=field['dashed_name'],
                 value_name=value_details['name']
@@ -380,8 +380,8 @@ def expected_event_types_template():
 
 def field_values_page_template():
     return '''
-[[ecs-accepted-values-{dashed_name}]]
-=== Accepted Values for {flat_name}
+[[ecs-allowed-values-{dashed_name}]]
+=== Allowed Values for {flat_name}
 
 {field_description}
 

From c614d2a66bf467da42f8793f0d227d23bb8bb6d2 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Fri, 13 Dec 2019 15:57:44 -0500
Subject: [PATCH 10/27] Add static warning text

---
 docs/field-values.asciidoc            | 20 ++++++++++++++++++++
 scripts/generators/asciidoc_fields.py |  5 +++++
 2 files changed, 25 insertions(+)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index e56d3d39a4..31583b4a00 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -25,6 +25,11 @@ The kind of the event.
 
 This gives information about what type of information the event contains, without being specific to the contents of the event.
 
+NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+and official ECS documentation should be considered official.
+Use of any other values may result in incompatible implementations
+that will require subsequent breaking changes.
+
 *Table of Contents*
 
 * <<ecs-event-kind-alert,alert>>
@@ -95,6 +100,11 @@ Event category.
 
 This contains high-level information about the contents of the event. It is more generic than `event.action`, in the sense that typically a category contains multiple actions.
 
+NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+and official ECS documentation should be considered official.
+Use of any other values may result in incompatible implementations
+that will require subsequent breaking changes.
+
 *Table of Contents*
 
 * <<ecs-event-category-authentication,authentication>>
@@ -243,6 +253,11 @@ access, error, info
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+and official ECS documentation should be considered official.
+Use of any other values may result in incompatible implementations
+that will require subsequent breaking changes.
+
 *Table of Contents*
 
 * <<ecs-event-type-access,access>>
@@ -373,6 +388,11 @@ The outcome of the event.
 
 If the event describes an action, this fields contains the outcome of that action.
 
+NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+and official ECS documentation should be considered official.
+Use of any other values may result in incompatible implementations
+that will require subsequent breaking changes.
+
 *Table of Contents*
 
 * <<ecs-event-outcome-failure,failure>>
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 2605c7252d..b2069a48b6 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -385,6 +385,11 @@ def field_values_page_template():
 
 {field_description}
 
+NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+and official ECS documentation should be considered official.
+Use of any other values may result in incompatible implementations
+that will require subsequent breaking changes.
+
 *Table of Contents*
 
 '''

From 9adcb7cb246f7d4d1b8ed03bae94391cca573f75 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 09:18:39 -0500
Subject: [PATCH 11/27] make debugging output less verbose

---
 scripts/generators/asciidoc_fields.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index b2069a48b6..875731a3a2 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -357,7 +357,6 @@ def render_field_values_page(field):
             )
     except UnicodeEncodeError:
         print("Problem with field {}, field value:".format(field['flat_name']))
-        # print(heading + toc + body)
         print(value_details)
         raise
     return heading + toc + body

From d30d9aa2cdb1afbbb4b614ca3c922a19b21f4af5 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 09:30:18 -0500
Subject: [PATCH 12/27] Integrate Mike's out of band feedback

---
 code/go/ecs/event.go           |  35 ++++---
 docs/field-details.asciidoc    |  22 +++--
 docs/field-values.asciidoc     |  70 +++++---------
 generated/beats/fields.ecs.yml |  40 +++++---
 generated/csv/fields.csv       |   8 +-
 generated/ecs/ecs_flat.yml     | 149 +++++++++++++-----------------
 generated/ecs/ecs_nested.yml   | 162 ++++++++++++++-------------------
 schemas/event.yml              | 148 +++++++++++++-----------------
 scripts/helper.py              |  21 +++--
 9 files changed, 288 insertions(+), 367 deletions(-)

diff --git a/code/go/ecs/event.go b/code/go/ecs/event.go
index 96eb2e8caa..005a6d8376 100644
--- a/code/go/ecs/event.go
+++ b/code/go/ecs/event.go
@@ -43,15 +43,20 @@ type Event struct {
 	// example of this is the Windows Event ID.
 	Code string `ecs:"code"`
 
-	// The kind of the event.
-	// This gives information about what type of information the event
-	// contains, without being specific to the contents of the event.
+	// This is one of four ECS Categorization Fields, and indicates the highest
+	// level in the ECS category hierarchy.
+	// `event.kind` gives high-level information about what type of information
+	// the event contains, without being specific to the contents of the event.
+	// For example, values of this field distinguish alert events from metric
+	// events.
 	Kind string `ecs:"kind"`
 
-	// Event category.
-	// This contains high-level information about the contents of the event. It
-	// is more generic than `event.action`, in the sense that typically a
-	// category contains multiple actions.
+	// This is one of four ECS Categorization Fields, and indicates the second
+	// level in the ECS category hierarchy.
+	// `event.category` represents the "big buckets" of ECS categories. For
+	// example, filtering on `event.category:process` yields all events
+	// relating to process activity. This field is closely related to
+	// `event.type`, which is used as a subcategory.
 	Category string `ecs:"category"`
 
 	// The action captured by the event.
@@ -60,13 +65,19 @@ type Event struct {
 	// `file-created`. The value is normally defined by the implementer.
 	Action string `ecs:"action"`
 
-	// The outcome of the event.
-	// If the event describes an action, this fields contains the outcome of
-	// that action.
+	// This is one of four ECS Categorization Fields, and indicates the lowest
+	// level in the ECS category hierarchy.
+	// `event.outcome` simply denotes whether the event represent a success or
+	// a failure. Note that not all events will have an associated outcome. For
+	// example, this field is generally not populated for metric events or
+	// events with `event.type:info`.
 	Outcome string `ecs:"outcome"`
 
-	// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
-	// tempor incididunt ut labore et dolore magna aliqua.
+	// This is one of four ECS Categorization Fields, and indicates the third
+	// level in the ECS category hierarchy.
+	// `event.type` represents a categorization "sub-bucket" that, when used
+	// along with the `event.category` field values, enables filtering events
+	// down to a level appropriate for single visualization.
 	Type string `ecs:"type"`
 
 	// Name of the module this data is coming from.
diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index 4dc2ec5f3d..3a4321ef56 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1135,9 +1135,9 @@ example: `user-password-change`
 // ===============================================================
 
 | event.category
-| Event category.
+| This is one of four ECS Categorization Fields, and indicates the second level in the ECS category hierarchy.
 
-This contains high-level information about the contents of the event. It is more generic than `event.action`, in the sense that typically a category contains multiple actions.
+`event.category` represents the "big buckets" of ECS categories. For example, filtering on `event.category:process` yields all events relating to process activity. This field is closely related to `event.type`, which is used as a subcategory.
 
 type: keyword
 
@@ -1261,9 +1261,9 @@ example: `2016-05-23 08:05:35.101000`
 // ===============================================================
 
 | event.kind
-| The kind of the event.
+| This is one of four ECS Categorization Fields, and indicates the highest level in the ECS category hierarchy.
 
-This gives information about what type of information the event contains, without being specific to the contents of the event.
+`event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events.
 
 type: keyword
 
@@ -1276,7 +1276,7 @@ To learn more about when to use which value, visit the page
 <<ecs-allowed-values-event-kind,allowed values for event.kind>>
 
 
-| extended
+| core
 
 // ===============================================================
 
@@ -1307,9 +1307,9 @@ example: `Sep 19 08:26:10 host CEF:0&#124;Security&#124; threatmanager&#124;1.0&
 // ===============================================================
 
 | event.outcome
-| The outcome of the event.
+| This is one of four ECS Categorization Fields, and indicates the lowest level in the ECS category hierarchy.
 
-If the event describes an action, this fields contains the outcome of that action.
+`event.outcome` simply denotes whether the event represent a success or a failure. Note that not all events will have an associated outcome. For example, this field is generally not populated for metric events or events with `event.type:info`.
 
 type: keyword
 
@@ -1322,7 +1322,7 @@ To learn more about when to use which value, visit the page
 <<ecs-allowed-values-event-outcome,allowed values for event.outcome>>
 
 
-| extended
+| core
 
 // ===============================================================
 
@@ -1416,14 +1416,16 @@ type: keyword
 // ===============================================================
 
 | event.type
-| Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+| This is one of four ECS Categorization Fields, and indicates the third level in the ECS category hierarchy.
+
+`event.type` represents a categorization "sub-bucket" that, when used along with the `event.category` field values, enables filtering events down to a level appropriate for single visualization.
 
 type: keyword
 
 
 *Important*: The field value must be one of the following:
 
-access, allowed, change, creation, deletion, denied, end, error, info, installation, protocol, start
+access, change, creation, deletion, end, error, info, installation, start
 
 To learn more about when to use which value, visit the page
 <<ecs-allowed-values-event-type,allowed values for event.type>>
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 31583b4a00..504a485b50 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -21,9 +21,9 @@ ECS defines four Categorization Fields for this purpose, each of which falls und
 [[ecs-allowed-values-event-kind]]
 === Allowed Values for event.kind
 
-The kind of the event.
+This is one of four ECS Categorization Fields, and indicates the highest level in the ECS category hierarchy.
 
-This gives information about what type of information the event contains, without being specific to the contents of the event.
+`event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events.
 
 NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
@@ -52,7 +52,7 @@ that will require subsequent breaking changes.
 [[ecs-event-kind-event]]
 ==== event
 
-It may sound a bit redundant, but `event.kind:event` is the most general and most common value of this field. It is used to represent events that indicate that something happened.
+`event.kind:event` is the most general and most common value of this field. It is used to represent events that indicate that something happened.
 
 
 
@@ -70,7 +70,7 @@ Used to indicate that this event is a measurement taken at given point in time.
 [[ecs-event-kind-state]]
 ==== state
 
-Similar to metric, except that the entity being measured does not provide a numeric metric value, but rather one of a fixed set of conditions or states. For example a periodic event reporting a "fin_wait" state of a TCP connection on a host might use `event.type:state`.
+This value is similar to metric, except that the entity being measured does not provide a numeric metric value, but rather one of a fixed set of conditions or states. For example a periodic event reporting a "fin_wait" state of a TCP connection on a host might use `event.type:state`.
 
 
 
@@ -96,9 +96,9 @@ The signal value is used by Elastic Kibana apps, such as SIEM, for app-specific
 [[ecs-allowed-values-event-category]]
 === Allowed Values for event.category
 
-Event category.
+This is one of four ECS Categorization Fields, and indicates the second level in the ECS category hierarchy.
 
-This contains high-level information about the contents of the event. It is more generic than `event.action`, in the sense that typically a category contains multiple actions.
+`event.category` represents the "big buckets" of ECS categories. For example, filtering on `event.category:process` yields all events relating to process activity. This field is closely related to `event.type`, which is used as a subcategory.
 
 NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
@@ -122,7 +122,7 @@ that will require subsequent breaking changes.
 [[ecs-event-category-authentication]]
 ==== authentication
 
-Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows Event logs, ssh logs, etc. Visualize and analyze events in this category to look for unusual login activity, failed logins, etc.
+Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows event logs, ssh logs, etc. Visualize and analyze events in this category to look for unusual login activity, failed logins, etc.
 
 
 
@@ -161,7 +161,7 @@ change, end, info, start
 [[ecs-event-category-file]]
 ==== file
 
-Relating to a set of information that has been created on, or has existed on a filesystem. Use this category of events to visualize and analyze the creation, access, permissions, transfers, and deletions of files. Events in this category can come from both host-based and network-based sources. An example source of a network-based detection of a file transfer would be the Zeek file.log.
+Relating to a set of information that has been created on, or has existed on a filesystem. Use this category of events to visualize and analyze the creation, access, and deletions of files. Events in this category can come from both host-based and network-based sources. An example source of a network-based detection of a file transfer would be the Zeek file.log.
 
 
 
@@ -174,7 +174,7 @@ change, creation, deletion, info
 [[ecs-event-category-host]]
 ==== host
 
-Events and metrics about hosts. Usually higher-level information about host activity from an external perspective. Different than operating system in the sense that events are usually externally visible and independent from the OS. "host" events are not meant to capture events that are simply "happening on a host". Use this category to visualize and analyze inventories of hosts, starting and ending of hosts, etc.
+Events and metrics about hosts. Usually higher-level information about host activity from an external perspective. Different than operating system in the sense that host events are usually externally visible and independent from the OS. `event.category:host` is not meant to indicate events that are simply "happening on a host". Use this category to visualize and analyze inventories of hosts, starting and ending of hosts, etc.
 
 
 
@@ -251,7 +251,9 @@ access, error, info
 [[ecs-allowed-values-event-type]]
 === Allowed Values for event.type
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+This is one of four ECS Categorization Fields, and indicates the third level in the ECS category hierarchy.
+
+`event.type` represents a categorization "sub-bucket" that, when used along with the `event.category` field values, enables filtering events down to a level appropriate for single visualization.
 
 NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
@@ -261,32 +263,20 @@ that will require subsequent breaking changes.
 *Table of Contents*
 
 * <<ecs-event-type-access,access>>
-* <<ecs-event-type-allowed,allowed>>
 * <<ecs-event-type-change,change>>
 * <<ecs-event-type-creation,creation>>
 * <<ecs-event-type-deletion,deletion>>
-* <<ecs-event-type-denied,denied>>
 * <<ecs-event-type-end,end>>
 * <<ecs-event-type-error,error>>
 * <<ecs-event-type-info,info>>
 * <<ecs-event-type-installation,installation>>
-* <<ecs-event-type-protocol,protocol>>
 * <<ecs-event-type-start,start>>
 
 [float]
 [[ecs-event-type-access]]
 ==== access
 
-The access event type is used for the subset of events within a category that indicate that something was accessed. Common examples include `event.category:database AND event.type:access`, or `event.category:file AND event.type:access`. Note for file access, include both directory listings and file opens in this subcategory. You can further distinguish access operations using the ECS `event.action` field.
-
-
-
-
-[float]
-[[ecs-event-type-allowed]]
-==== allowed
-
-The allow event type is used for the subset of events within a category that indicate that something was allowed. Common examples include `event.category:network AND event.type:allow` to indicate a network firewall event for which the firewall disposition was to allow the connection to complete. `event.category:network_flow AND event.type:allow` to indicate a network flow event that is also a network firewall event for which the firewall disposition was to allow the connection to complete.
+The access event type is used for the subset of events within a category that indicate that something was accessed. Common examples include `event.category:database AND event.type:access`, or `event.category:file AND event.type:access`. Note for file access, both directory listings and file opens should be included in this subcategory. You can further distinguish access operations using the ECS `event.action` field.
 
 
 
@@ -295,7 +285,7 @@ The allow event type is used for the subset of events within a category that ind
 [[ecs-event-type-change]]
 ==== change
 
-The change event type is used for the subset of events within a category that indicate that something has changed. If semantics best describe an event as modified, then include them in this subcategory. Common examples include `event.category:registry AND event.type:change`, and `event.category:file AND event.type:change`. You can further distinguish change operations using the ECS `event.action` field.
+The change event type is used for the subset of events within a category that indicate that something has changed. If semantics best describe an event as modified, then include them in this subcategory. Common examples include `event.category:process AND event.type:change`, and `event.category:file AND event.type:change`. You can further distinguish change operations using the ECS `event.action` field.
 
 
 
@@ -313,16 +303,7 @@ The create event type is used for the subset of events within a category that in
 [[ecs-event-type-deletion]]
 ==== deletion
 
-The delete event type is used for the subset of events within a category that indicate that something was deleted. Common examples include `event.category:file AND event.type:delete`, and `event.category:iam_user AND event.type:delete`, to indicate that a user has been deleted from an Identity and Access Management system.
-
-
-
-
-[float]
-[[ecs-event-type-denied]]
-==== denied
-
-The deny event type is used for the subset of events within a category that indicate that something was disallowed, blocked or denied. Common examples include `event.category:network AND event.type:deny` to indicate a network firewall event for which the firewall disposition was to deny the connection to complete. `event.category:network_flow AND event.type:deny` to indicate a network flow event that is also a network firewall event for which the firewall disposition was to deny the connection to complete. Note that the `event.action` field can be used to further describe the deny action with user-supplied values such as "drop", "reject", "block", "redirect", etc.
+The deletion event type is used for the subset of events within a category that indicate that something was deleted. A common example is `event.category:file AND event.type:deletion` to indicate that a file has been deleted.
 
 
 
@@ -331,7 +312,7 @@ The deny event type is used for the subset of events within a category that indi
 [[ecs-event-type-end]]
 ==== end
 
-The end event type is used for the subset of events within a category that indicate something has ended. Common examples include `event.category:process AND event.type:end`, and `event.category:network_flow AND event.type:end` to indicate a flow record event that is sent at the completion of the network flow.
+The end event type is used for the subset of events within a category that indicate something has ended. A common example is `event.category:process AND event.type:end`.
 
 
 
@@ -340,7 +321,7 @@ The end event type is used for the subset of events within a category that indic
 [[ecs-event-type-error]]
 ==== error
 
-The error event type is used for the subset of events within a category that indicate or describe an error. Common examples include `event.category:application AND event.type:error` and `event.category:database AND event.type:error`. Note that pipeline errors that occur during the event ingestion process should not use this `event.type` value. Instead, they should use the `event.kind:pipeline_error`.
+The error event type is used for the subset of events within a category that indicate or describe an error. A common example is `event.category:database AND event.type:error`. Note that pipeline errors that occur during the event ingestion process should not use this `event.type` value. Instead, they should use `event.kind:pipeline_error`.
 
 
 
@@ -349,7 +330,7 @@ The error event type is used for the subset of events within a category that ind
 [[ecs-event-type-info]]
 ==== info
 
-The info event type is used for the subset of events within a category that indicate that they are purely informational, and don't report a state change, action. For example, an initial run of a file integrity monitoring system (FIM) where an agent reports all files under management would fall into the "info" subcategory. Similarly, a dump of all current running processes (as opposed to reporting that process start/end) would fall into the "info" subcategory. Additional common examples include `event.category:registry AND event.type:info`, and `event.category:intrusion_detection AND event.type:info`.
+The info event type is used for the subset of events within a category that indicate that they are purely informational, and don't report a state change, or any type of action. For example, an initial run of a file integrity monitoring system (FIM), where an agent reports all files under management, would fall into the "info" subcategory. Similarly, an event containing a dump of all currently running processes (as opposed to reporting that a process started/ended) would fall into the "info" subcategory. An additional common examples is `event.category:intrusion_detection AND event.type:info`.
 
 
 
@@ -358,16 +339,7 @@ The info event type is used for the subset of events within a category that indi
 [[ecs-event-type-installation]]
 ==== installation
 
-The install event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:install`.
-
-
-
-
-[float]
-[[ecs-event-type-protocol]]
-==== protocol
-
-The protocol event type is used for the subset of events within a category that indicate that they contain protocol details or analysis. Generally, network traffic and network flows that contain protocol details will fall into this subcategory. Common examples include `event.category:network AND event.type:protocol`, and `event.category:network_flow AND event.type:protocol`. Note for when the protocol subcategory is used, you can further distinguish protocols using the ECS `network.protocol` field.
+The installation event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:installed`.
 
 
 
@@ -384,9 +356,9 @@ The start event type is used for the subset of events within a category that ind
 [[ecs-allowed-values-event-outcome]]
 === Allowed Values for event.outcome
 
-The outcome of the event.
+This is one of four ECS Categorization Fields, and indicates the lowest level in the ECS category hierarchy.
 
-If the event describes an action, this fields contains the outcome of that action.
+`event.outcome` simply denotes whether the event represent a success or a failure. Note that not all events will have an associated outcome. For example, this field is generally not populated for metric events or events with `event.type:info`.
 
 NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml
index 09b0a65044..c356b82e86 100644
--- a/generated/beats/fields.ecs.yml
+++ b/generated/beats/fields.ecs.yml
@@ -945,11 +945,13 @@
       level: core
       type: keyword
       ignore_above: 1024
-      description: 'Event category.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        second level in the ECS category hierarchy.
 
-        This contains high-level information about the contents of the event. It is
-        more generic than `event.action`, in the sense that typically a category contains
-        multiple actions.'
+        `event.category` represents the "big buckets" of ECS categories. For example,
+        filtering on `event.category:process` yields all events relating to process
+        activity. This field is closely related to `event.type`, which is used as
+        a subcategory.'
       example: authentication
     - name: code
       level: extended
@@ -1032,14 +1034,16 @@
         look like this: `@timestamp` < `event.created` < `event.ingested`.'
       example: 2016-05-23 08:05:35.101000
     - name: kind
-      level: extended
+      level: core
       type: keyword
       ignore_above: 1024
-      description: 'The kind of the event.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        highest level in the ECS category hierarchy.
 
-        This gives information about what type of information the event contains,
-        without being specific to the contents of the event.'
-      example: event
+        `event.kind` gives high-level information about what type of information the
+        event contains, without being specific to the contents of the event. For example,
+        values of this field distinguish alert events from metric events.'
+      example: alert
     - name: module
       level: core
       type: keyword
@@ -1061,13 +1065,15 @@
       example: Sep 19 08:26:10 host CEF:0&#124;Security&#124; threatmanager&#124;1.0&#124;100&#124;
         worm successfully stopped&#124;10&#124;src=10.0.0.1 dst=2.1.2.2spt=1232
     - name: outcome
-      level: extended
+      level: core
       type: keyword
       ignore_above: 1024
-      description: 'The outcome of the event.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        lowest level in the ECS category hierarchy.
 
-        If the event describes an action, this fields contains the outcome of that
-        action.'
+        `event.outcome` simply denotes whether the event represent a success or a
+        failure. Note that not all events will have an associated outcome. For example,
+        this field is generally not populated for metric events or events with `event.type:info`.'
       example: success
     - name: provider
       level: extended
@@ -1135,8 +1141,12 @@
       level: core
       type: keyword
       ignore_above: 1024
-      description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-        eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        third level in the ECS category hierarchy.
+
+        `event.type` represents a categorization "sub-bucket" that, when used along
+        with the `event.category` field values, enables filtering events down to a
+        level appropriate for single visualization.'
   - name: file
     title: File
     group: 2
diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv
index d90632b38e..408f10d9a6 100644
--- a/generated/csv/fields.csv
+++ b/generated/csv/fields.csv
@@ -116,7 +116,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,false,error,error.stack_trace.text,text,extended,,The stack trace of this error in plain text.
 1.4.0-dev,true,error,error.type,keyword,extended,java.lang.NullPointerException,"The type of the error, for example the class name of the exception."
 1.4.0-dev,true,event,event.action,keyword,core,user-password-change,The action captured by the event.
-1.4.0-dev,true,event,event.category,keyword,core,authentication,Event category.
+1.4.0-dev,true,event,event.category,keyword,core,authentication,Event category. (Categorization Field)
 1.4.0-dev,true,event,event.code,keyword,extended,4648,Identification code for this event.
 1.4.0-dev,true,event,event.created,date,core,2016-05-23 08:05:34.857000,Time when the event was first read by an agent or by your pipeline.
 1.4.0-dev,true,event,event.dataset,keyword,core,apache.access,Name of the dataset.
@@ -125,10 +125,10 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,true,event,event.hash,keyword,extended,123456789012345678901234567890ABCD,Hash (perhaps logstash fingerprint) of raw field to be able to demonstrate log integrity.
 1.4.0-dev,true,event,event.id,keyword,core,8a4f500d,Unique ID to describe the event.
 1.4.0-dev,true,event,event.ingested,date,core,2016-05-23 08:05:35.101000,Timestamp when an event arrived in the central data store.
-1.4.0-dev,true,event,event.kind,keyword,extended,event,The kind of the event.
+1.4.0-dev,true,event,event.kind,keyword,core,alert,The kind of the event. (Categorization Field)
 1.4.0-dev,true,event,event.module,keyword,core,apache,Name of the module this data is coming from.
 1.4.0-dev,false,event,event.original,keyword,core,Sep 19 08:26:10 host CEF:0&#124;Security&#124; threatmanager&#124;1.0&#124;100&#124; worm successfully stopped&#124;10&#124;src=10.0.0.1 dst=2.1.2.2spt=1232,Raw text message of entire event.
-1.4.0-dev,true,event,event.outcome,keyword,extended,success,The outcome of the event.
+1.4.0-dev,true,event,event.outcome,keyword,core,success,The outcome of the event. (Categorization Field)
 1.4.0-dev,true,event,event.provider,keyword,extended,kernel,Source of the event.
 1.4.0-dev,true,event,event.risk_score,float,core,,Risk score or priority of the event (e.g. security solutions). Use your system's original value here.
 1.4.0-dev,true,event,event.risk_score_norm,float,extended,,Normalized risk score or priority of the event (0-100).
@@ -136,7 +136,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,true,event,event.severity,long,core,7,Numeric severity of the event.
 1.4.0-dev,true,event,event.start,date,extended,,event.start contains the date when the event started or when the activity was first observed.
 1.4.0-dev,true,event,event.timezone,keyword,extended,,Event time zone.
-1.4.0-dev,true,event,event.type,keyword,core,,Reserved for future usage.
+1.4.0-dev,true,event,event.type,keyword,core,,Event type (Categorization Field)
 1.4.0-dev,true,file,file.accessed,date,extended,,Last time the file was accessed.
 1.4.0-dev,true,file,file.attributes,keyword,extended,"[""readonly"", ""system""]",Array of file attributes.
 1.4.0-dev,true,file,file.created,date,extended,,File creation time.
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index 15492a75fc..09ce92e862 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1374,7 +1374,7 @@ event.category:
   allowed_values:
   - description: 'Events in this category are related to the challenge and response
       process in which credentials are supplied and verified to allow the creation
-      of a session. Common sources for these logs are Windows Event logs, ssh logs,
+      of a session. Common sources for these logs are Windows event logs, ssh logs,
       etc. Visualize and analyze events in this category to look for unusual login
       activity, failed logins, etc.
 
@@ -1411,10 +1411,9 @@ event.category:
     name: driver
   - description: 'Relating to a set of information that has been created on, or has
       existed on a filesystem. Use this category of events to visualize and analyze
-      the creation, access, permissions, transfers, and deletions of files. Events
-      in this category can come from both host-based and network-based sources. An
-      example source of a network-based detection of a file transfer would be the
-      Zeek file.log.
+      the creation, access, and deletions of files. Events in this category can come
+      from both host-based and network-based sources. An example source of a network-based
+      detection of a file transfer would be the Zeek file.log.
 
       '
     expected_event_types:
@@ -1425,10 +1424,10 @@ event.category:
     name: file
   - description: 'Events and metrics about hosts. Usually higher-level information
       about host activity from an external perspective. Different than operating system
-      in the sense that events are usually externally visible and independent from
-      the OS. "host" events are not meant to capture events that are simply "happening
-      on a host". Use this category to visualize and analyze inventories of hosts,
-      starting and ending of hosts, etc.
+      in the sense that host events are usually externally visible and independent
+      from the OS. `event.category:host` is not meant to indicate events that are
+      simply "happening on a host". Use this category to visualize and analyze inventories
+      of hosts, starting and ending of hosts, etc.
 
       '
     expected_event_types:
@@ -1493,18 +1492,19 @@ event.category:
     - info
     name: web
   dashed_name: event-category
-  description: 'Event category.
+  description: 'This is one of four ECS Categorization Fields, and indicates the second
+    level in the ECS category hierarchy.
 
-    This contains high-level information about the contents of the event. It is more
-    generic than `event.action`, in the sense that typically a category contains multiple
-    actions.'
+    `event.category` represents the "big buckets" of ECS categories. For example,
+    filtering on `event.category:process` yields all events relating to process activity.
+    This field is closely related to `event.type`, which is used as a subcategory.'
   example: authentication
   flat_name: event.category
   ignore_above: 1024
   level: core
   name: category
   order: 3
-  short: Event category.
+  short: Event category. (Categorization Field)
   type: keyword
 event.code:
   dashed_name: event-code
@@ -1636,9 +1636,8 @@ event.kind:
 
       '
     name: alert
-  - description: 'It may sound a bit redundant, but `event.kind:event` is the most
-      general and most common value of this field. It is used to represent events
-      that indicate that something happened.
+  - description: '`event.kind:event` is the most general and most common value of
+      this field. It is used to represent events that indicate that something happened.
 
       '
     name: event
@@ -1649,8 +1648,8 @@ event.kind:
 
       '
     name: metric
-  - description: 'Similar to metric, except that the entity being measured does not
-      provide a numeric metric value, but rather one of a fixed set of conditions
+  - description: 'This value is similar to metric, except that the entity being measured
+      does not provide a numeric metric value, but rather one of a fixed set of conditions
       or states. For example a periodic event reporting a "fin_wait" state of a TCP
       connection on a host might use `event.type:state`.
 
@@ -1669,17 +1668,19 @@ event.kind:
       '
     name: signal
   dashed_name: event-kind
-  description: 'The kind of the event.
+  description: 'This is one of four ECS Categorization Fields, and indicates the highest
+    level in the ECS category hierarchy.
 
-    This gives information about what type of information the event contains, without
-    being specific to the contents of the event.'
-  example: event
+    `event.kind` gives high-level information about what type of information the event
+    contains, without being specific to the contents of the event. For example, values
+    of this field distinguish alert events from metric events.'
+  example: alert
   flat_name: event.kind
   ignore_above: 1024
-  level: extended
+  level: core
   name: kind
   order: 2
-  short: The kind of the event.
+  short: The kind of the event. (Categorization Field)
   type: keyword
 event.module:
   dashed_name: event-module
@@ -1735,16 +1736,19 @@ event.outcome:
       '
     name: unknown
   dashed_name: event-outcome
-  description: 'The outcome of the event.
+  description: 'This is one of four ECS Categorization Fields, and indicates the lowest
+    level in the ECS category hierarchy.
 
-    If the event describes an action, this fields contains the outcome of that action.'
+    `event.outcome` simply denotes whether the event represent a success or a failure.
+    Note that not all events will have an associated outcome. For example, this field
+    is generally not populated for metric events or events with `event.type:info`.'
   example: success
   flat_name: event.outcome
   ignore_above: 1024
-  level: extended
+  level: core
   name: outcome
   order: 5
-  short: The outcome of the event.
+  short: The outcome of the event. (Categorization Field)
   type: keyword
 event.provider:
   dashed_name: event-provider
@@ -1849,26 +1853,16 @@ event.type:
   - description: 'The access event type is used for the subset of events within a
       category that indicate that something was accessed. Common examples include
       `event.category:database AND event.type:access`, or `event.category:file AND
-      event.type:access`. Note for file access, include both directory listings and
-      file opens in this subcategory. You can further distinguish access operations
+      event.type:access`. Note for file access, both directory listings and file opens
+      should be included in this subcategory. You can further distinguish access operations
       using the ECS `event.action` field.
 
       '
     name: access
-  - description: 'The allow event type is used for the subset of events within a category
-      that indicate that something was allowed. Common examples include `event.category:network
-      AND event.type:allow` to indicate a network firewall event for which the firewall
-      disposition was to allow the connection to complete. `event.category:network_flow
-      AND event.type:allow` to indicate a network flow event that is also a network
-      firewall event for which the firewall disposition was to allow the connection
-      to complete.
-
-      '
-    name: allowed
   - description: 'The change event type is used for the subset of events within a
       category that indicate that something has changed. If semantics best describe
       an event as modified, then include them in this subcategory. Common examples
-      include `event.category:registry AND event.type:change`, and `event.category:file
+      include `event.category:process AND event.type:change`, and `event.category:file
       AND event.type:change`. You can further distinguish change operations using
       the ECS `event.action` field.
 
@@ -1880,68 +1874,43 @@ event.type:
 
       '
     name: creation
-  - description: 'The delete event type is used for the subset of events within a
-      category that indicate that something was deleted. Common examples include `event.category:file
-      AND event.type:delete`, and `event.category:iam_user AND event.type:delete`,
-      to indicate that a user has been deleted from an Identity and Access Management
-      system.
+  - description: 'The deletion event type is used for the subset of events within
+      a category that indicate that something was deleted. A common example is `event.category:file
+      AND event.type:deletion` to indicate that a file has been deleted.
 
       '
     name: deletion
-  - description: 'The deny event type is used for the subset of events within a category
-      that indicate that something was disallowed, blocked or denied. Common examples
-      include `event.category:network AND event.type:deny` to indicate a network firewall
-      event for which the firewall disposition was to deny the connection to complete.
-      `event.category:network_flow AND event.type:deny` to indicate a network flow
-      event that is also a network firewall event for which the firewall disposition
-      was to deny the connection to complete. Note that the `event.action` field can
-      be used to further describe the deny action with user-supplied values such as
-      "drop", "reject", "block", "redirect", etc.
-
-      '
-    name: denied
   - description: 'The end event type is used for the subset of events within a category
-      that indicate something has ended. Common examples include `event.category:process
-      AND event.type:end`, and `event.category:network_flow AND event.type:end` to
-      indicate a flow record event that is sent at the completion of the network flow.
+      that indicate something has ended. A common example is `event.category:process
+      AND event.type:end`.
 
       '
     name: end
   - description: 'The error event type is used for the subset of events within a category
-      that indicate or describe an error. Common examples include `event.category:application
-      AND event.type:error` and `event.category:database AND event.type:error`. Note
-      that pipeline errors that occur during the event ingestion process should not
-      use this `event.type` value. Instead, they should use the `event.kind:pipeline_error`.
+      that indicate or describe an error. A common example is `event.category:database
+      AND event.type:error`. Note that pipeline errors that occur during the event
+      ingestion process should not use this `event.type` value. Instead, they should
+      use `event.kind:pipeline_error`.
 
       '
     name: error
   - description: 'The info event type is used for the subset of events within a category
       that indicate that they are purely informational, and don''t report a state
-      change, action. For example, an initial run of a file integrity monitoring system
-      (FIM) where an agent reports all files under management would fall into the
-      "info" subcategory. Similarly, a dump of all current running processes (as opposed
-      to reporting that process start/end) would fall into the "info" subcategory.
-      Additional common examples include `event.category:registry AND event.type:info`,
-      and `event.category:intrusion_detection AND event.type:info`.
+      change, or any type of action. For example, an initial run of a file integrity
+      monitoring system (FIM), where an agent reports all files under management,
+      would fall into the "info" subcategory. Similarly, an event containing a dump
+      of all currently running processes (as opposed to reporting that a process started/ended)
+      would fall into the "info" subcategory. An additional common examples is `event.category:intrusion_detection
+      AND event.type:info`.
 
       '
     name: info
-  - description: 'The install event type is used for the subset of events within a
-      category that indicate that something was installed. A common example is `event.category:package`
-      AND `event.type:install`.
+  - description: 'The installation event type is used for the subset of events within
+      a category that indicate that something was installed. A common example is `event.category:package`
+      AND `event.type:installed`.
 
       '
     name: installation
-  - description: 'The protocol event type is used for the subset of events within
-      a category that indicate that they contain protocol details or analysis. Generally,
-      network traffic and network flows that contain protocol details will fall into
-      this subcategory. Common examples include `event.category:network AND event.type:protocol`,
-      and `event.category:network_flow AND event.type:protocol`. Note for when the
-      protocol subcategory is used, you can further distinguish protocols using the
-      ECS `network.protocol` field.
-
-      '
-    name: protocol
   - description: 'The start event type is used for the subset of events within a category
       that indicate something has started. A common example is `event.category:process
       AND event.type:start`.
@@ -1949,14 +1918,18 @@ event.type:
       '
     name: start
   dashed_name: event-type
-  description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
-    tempor incididunt ut labore et dolore magna aliqua.
+  description: 'This is one of four ECS Categorization Fields, and indicates the third
+    level in the ECS category hierarchy.
+
+    `event.type` represents a categorization "sub-bucket" that, when used along with
+    the `event.category` field values, enables filtering events down to a level appropriate
+    for single visualization.'
   flat_name: event.type
   ignore_above: 1024
   level: core
   name: type
   order: 6
-  short: Reserved for future usage.
+  short: Event type (Categorization Field)
   type: keyword
 file.accessed:
   dashed_name: file-accessed
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index 43529e6625..2c22cf7d93 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1588,7 +1588,7 @@ event:
       allowed_values:
       - description: 'Events in this category are related to the challenge and response
           process in which credentials are supplied and verified to allow the creation
-          of a session. Common sources for these logs are Windows Event logs, ssh
+          of a session. Common sources for these logs are Windows event logs, ssh
           logs, etc. Visualize and analyze events in this category to look for unusual
           login activity, failed logins, etc.
 
@@ -1625,10 +1625,9 @@ event:
         name: driver
       - description: 'Relating to a set of information that has been created on, or
           has existed on a filesystem. Use this category of events to visualize and
-          analyze the creation, access, permissions, transfers, and deletions of files.
-          Events in this category can come from both host-based and network-based
-          sources. An example source of a network-based detection of a file transfer
-          would be the Zeek file.log.
+          analyze the creation, access, and deletions of files. Events in this category
+          can come from both host-based and network-based sources. An example source
+          of a network-based detection of a file transfer would be the Zeek file.log.
 
           '
         expected_event_types:
@@ -1639,10 +1638,10 @@ event:
         name: file
       - description: 'Events and metrics about hosts. Usually higher-level information
           about host activity from an external perspective. Different than operating
-          system in the sense that events are usually externally visible and independent
-          from the OS. "host" events are not meant to capture events that are simply
-          "happening on a host". Use this category to visualize and analyze inventories
-          of hosts, starting and ending of hosts, etc.
+          system in the sense that host events are usually externally visible and
+          independent from the OS. `event.category:host` is not meant to indicate
+          events that are simply "happening on a host". Use this category to visualize
+          and analyze inventories of hosts, starting and ending of hosts, etc.
 
           '
         expected_event_types:
@@ -1708,18 +1707,20 @@ event:
         - info
         name: web
       dashed_name: event-category
-      description: 'Event category.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        second level in the ECS category hierarchy.
 
-        This contains high-level information about the contents of the event. It is
-        more generic than `event.action`, in the sense that typically a category contains
-        multiple actions.'
+        `event.category` represents the "big buckets" of ECS categories. For example,
+        filtering on `event.category:process` yields all events relating to process
+        activity. This field is closely related to `event.type`, which is used as
+        a subcategory.'
       example: authentication
       flat_name: event.category
       ignore_above: 1024
       level: core
       name: category
       order: 3
-      short: Event category.
+      short: Event category. (Categorization Field)
       type: keyword
     code:
       dashed_name: event-code
@@ -1853,9 +1854,9 @@ event:
 
           '
         name: alert
-      - description: 'It may sound a bit redundant, but `event.kind:event` is the
-          most general and most common value of this field. It is used to represent
-          events that indicate that something happened.
+      - description: '`event.kind:event` is the most general and most common value
+          of this field. It is used to represent events that indicate that something
+          happened.
 
           '
         name: event
@@ -1866,10 +1867,10 @@ event:
 
           '
         name: metric
-      - description: 'Similar to metric, except that the entity being measured does
-          not provide a numeric metric value, but rather one of a fixed set of conditions
-          or states. For example a periodic event reporting a "fin_wait" state of
-          a TCP connection on a host might use `event.type:state`.
+      - description: 'This value is similar to metric, except that the entity being
+          measured does not provide a numeric metric value, but rather one of a fixed
+          set of conditions or states. For example a periodic event reporting a "fin_wait"
+          state of a TCP connection on a host might use `event.type:state`.
 
           '
         name: state
@@ -1886,17 +1887,19 @@ event:
           '
         name: signal
       dashed_name: event-kind
-      description: 'The kind of the event.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        highest level in the ECS category hierarchy.
 
-        This gives information about what type of information the event contains,
-        without being specific to the contents of the event.'
-      example: event
+        `event.kind` gives high-level information about what type of information the
+        event contains, without being specific to the contents of the event. For example,
+        values of this field distinguish alert events from metric events.'
+      example: alert
       flat_name: event.kind
       ignore_above: 1024
-      level: extended
+      level: core
       name: kind
       order: 2
-      short: The kind of the event.
+      short: The kind of the event. (Categorization Field)
       type: keyword
     module:
       dashed_name: event-module
@@ -1952,17 +1955,19 @@ event:
           '
         name: unknown
       dashed_name: event-outcome
-      description: 'The outcome of the event.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        lowest level in the ECS category hierarchy.
 
-        If the event describes an action, this fields contains the outcome of that
-        action.'
+        `event.outcome` simply denotes whether the event represent a success or a
+        failure. Note that not all events will have an associated outcome. For example,
+        this field is generally not populated for metric events or events with `event.type:info`.'
       example: success
       flat_name: event.outcome
       ignore_above: 1024
-      level: extended
+      level: core
       name: outcome
       order: 5
-      short: The outcome of the event.
+      short: The outcome of the event. (Categorization Field)
       type: keyword
     provider:
       dashed_name: event-provider
@@ -2068,26 +2073,16 @@ event:
       - description: 'The access event type is used for the subset of events within
           a category that indicate that something was accessed. Common examples include
           `event.category:database AND event.type:access`, or `event.category:file
-          AND event.type:access`. Note for file access, include both directory listings
-          and file opens in this subcategory. You can further distinguish access operations
-          using the ECS `event.action` field.
+          AND event.type:access`. Note for file access, both directory listings and
+          file opens should be included in this subcategory. You can further distinguish
+          access operations using the ECS `event.action` field.
 
           '
         name: access
-      - description: 'The allow event type is used for the subset of events within
-          a category that indicate that something was allowed. Common examples include
-          `event.category:network AND event.type:allow` to indicate a network firewall
-          event for which the firewall disposition was to allow the connection to
-          complete. `event.category:network_flow AND event.type:allow` to indicate
-          a network flow event that is also a network firewall event for which the
-          firewall disposition was to allow the connection to complete.
-
-          '
-        name: allowed
       - description: 'The change event type is used for the subset of events within
           a category that indicate that something has changed. If semantics best describe
           an event as modified, then include them in this subcategory. Common examples
-          include `event.category:registry AND event.type:change`, and `event.category:file
+          include `event.category:process AND event.type:change`, and `event.category:file
           AND event.type:change`. You can further distinguish change operations using
           the ECS `event.action` field.
 
@@ -2099,70 +2094,45 @@ event:
 
           '
         name: creation
-      - description: 'The delete event type is used for the subset of events within
-          a category that indicate that something was deleted. Common examples include
-          `event.category:file AND event.type:delete`, and `event.category:iam_user
-          AND event.type:delete`, to indicate that a user has been deleted from an
-          Identity and Access Management system.
+      - description: 'The deletion event type is used for the subset of events within
+          a category that indicate that something was deleted. A common example is
+          `event.category:file AND event.type:deletion` to indicate that a file has
+          been deleted.
 
           '
         name: deletion
-      - description: 'The deny event type is used for the subset of events within
-          a category that indicate that something was disallowed, blocked or denied.
-          Common examples include `event.category:network AND event.type:deny` to
-          indicate a network firewall event for which the firewall disposition was
-          to deny the connection to complete. `event.category:network_flow AND event.type:deny`
-          to indicate a network flow event that is also a network firewall event for
-          which the firewall disposition was to deny the connection to complete. Note
-          that the `event.action` field can be used to further describe the deny action
-          with user-supplied values such as "drop", "reject", "block", "redirect",
-          etc.
-
-          '
-        name: denied
       - description: 'The end event type is used for the subset of events within a
-          category that indicate something has ended. Common examples include `event.category:process
-          AND event.type:end`, and `event.category:network_flow AND event.type:end`
-          to indicate a flow record event that is sent at the completion of the network
-          flow.
+          category that indicate something has ended. A common example is `event.category:process
+          AND event.type:end`.
 
           '
         name: end
       - description: 'The error event type is used for the subset of events within
-          a category that indicate or describe an error. Common examples include `event.category:application
-          AND event.type:error` and `event.category:database AND event.type:error`.
-          Note that pipeline errors that occur during the event ingestion process
-          should not use this `event.type` value. Instead, they should use the `event.kind:pipeline_error`.
+          a category that indicate or describe an error. A common example is `event.category:database
+          AND event.type:error`. Note that pipeline errors that occur during the event
+          ingestion process should not use this `event.type` value. Instead, they
+          should use `event.kind:pipeline_error`.
 
           '
         name: error
       - description: 'The info event type is used for the subset of events within
           a category that indicate that they are purely informational, and don''t
-          report a state change, action. For example, an initial run of a file integrity
-          monitoring system (FIM) where an agent reports all files under management
-          would fall into the "info" subcategory. Similarly, a dump of all current
-          running processes (as opposed to reporting that process start/end) would
-          fall into the "info" subcategory. Additional common examples include `event.category:registry
-          AND event.type:info`, and `event.category:intrusion_detection AND event.type:info`.
+          report a state change, or any type of action. For example, an initial run
+          of a file integrity monitoring system (FIM), where an agent reports all
+          files under management, would fall into the "info" subcategory. Similarly,
+          an event containing a dump of all currently running processes (as opposed
+          to reporting that a process started/ended) would fall into the "info" subcategory.
+          An additional common examples is `event.category:intrusion_detection AND
+          event.type:info`.
 
           '
         name: info
-      - description: 'The install event type is used for the subset of events within
-          a category that indicate that something was installed. A common example
-          is `event.category:package` AND `event.type:install`.
+      - description: 'The installation event type is used for the subset of events
+          within a category that indicate that something was installed. A common example
+          is `event.category:package` AND `event.type:installed`.
 
           '
         name: installation
-      - description: 'The protocol event type is used for the subset of events within
-          a category that indicate that they contain protocol details or analysis.
-          Generally, network traffic and network flows that contain protocol details
-          will fall into this subcategory. Common examples include `event.category:network
-          AND event.type:protocol`, and `event.category:network_flow AND event.type:protocol`.
-          Note for when the protocol subcategory is used, you can further distinguish
-          protocols using the ECS `network.protocol` field.
-
-          '
-        name: protocol
       - description: 'The start event type is used for the subset of events within
           a category that indicate something has started. A common example is `event.category:process
           AND event.type:start`.
@@ -2170,14 +2140,18 @@ event:
           '
         name: start
       dashed_name: event-type
-      description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-        eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      description: 'This is one of four ECS Categorization Fields, and indicates the
+        third level in the ECS category hierarchy.
+
+        `event.type` represents a categorization "sub-bucket" that, when used along
+        with the `event.category` field values, enables filtering events down to a
+        level appropriate for single visualization.'
       flat_name: event.type
       ignore_above: 1024
       level: core
       name: type
       order: 6
-      short: Reserved for future usage.
+      short: Event type (Categorization Field)
       type: keyword
   group: 2
   name: event
diff --git a/schemas/event.yml b/schemas/event.yml
index 5b1dc64580..70f430bf48 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -38,15 +38,18 @@
       example: 4648
 
     - name: kind
-      level: extended
+      level: core
       type: keyword
-      short: The kind of the event.
+      short: The kind of the event. (Categorization Field)
       description: >
-        The kind of the event.
-
-        This gives information about what type of information the event
-        contains, without being specific to the contents of the event.
-      example: event
+        This is one of four ECS Categorization Fields, and indicates the
+        highest level in the ECS category hierarchy.
+
+        `event.kind` gives high-level information about what type of information the
+        event contains, without being specific to the contents of the event.
+        For example, values of this field distinguish alert events from
+        metric events.
+      example: alert
       allowed_values:
         - name: alert
           description: >
@@ -57,9 +60,8 @@
             It is used to indicate that an alert was triggered.
         - name: event
           description: >
-            It may sound a bit redundant, but `event.kind:event` is the most general
-            and most common value of this field. It is used to represent events that
-            indicate that something happened.
+            `event.kind:event` is the most general and most common value of this
+            field. It is used to represent events that indicate that something happened.
         - name: metric
           description: >
             Used to indicate that this event is a measurement taken at given point in time.
@@ -67,7 +69,7 @@
             Events with `event.kind:metric` indicate that a measurement was taken.
         - name: state
           description: >
-            Similar to metric, except that the entity being measured does not
+            This value is similar to metric, except that the entity being measured does not
             provide a numeric metric value, but rather one of a fixed set of conditions or states.
             For example a periodic event reporting a "fin_wait" state of a TCP connection
             on a host might use `event.type:state`.
@@ -85,20 +87,21 @@
     - name: category
       level: core
       type: keyword
-      short: Event category.
+      short: Event category. (Categorization Field)
       description: >
-        Event category.
+        This is one of four ECS Categorization Fields, and indicates the
+        second level in the ECS category hierarchy.
 
-        This contains high-level information about the contents of the event. It
-        is more generic than `event.action`, in the sense that typically a
-        category contains multiple actions.
+        `event.category` represents the "big buckets" of ECS categories. For example,
+        filtering on `event.category:process` yields all events relating to process activity.
+        This field is closely related to `event.type`, which is used as a subcategory.
       example: authentication
       allowed_values:
         - name: authentication
           description: >
             Events in this category are related to the challenge and response process
             in which credentials are supplied and verified to allow the creation of a session.
-            Common sources for these logs are Windows Event logs, ssh logs, etc.
+            Common sources for these logs are Windows event logs, ssh logs, etc.
             Visualize and analyze events in this category to look for unusual login activity,
             failed logins, etc.
           expected_event_types:
@@ -132,7 +135,7 @@
           description: >
             Relating to a set of information that has been created on, or has existed on a filesystem.
             Use this category of events to visualize and analyze the creation, access,
-            permissions, transfers, and deletions of files. Events in this category can come
+            and deletions of files. Events in this category can come
             from both host-based and network-based sources. An example source of a network-based
             detection of a file transfer would be the Zeek file.log.
           expected_event_types:
@@ -144,10 +147,10 @@
           description: >
             Events and metrics about hosts. Usually higher-level information about host
             activity from an external perspective. Different than operating system
-            in the sense that events are usually externally visible and independent from the OS.
-            "host" events are not meant to capture events that are simply "happening on a host".
-            Use this category to visualize and analyze inventories of hosts,
-            starting and ending of hosts, etc.
+            in the sense that host events are usually externally visible and independent from the OS.
+            `event.category:host` is not meant to indicate events that are simply
+            "happening on a host". Use this category to visualize and analyze inventories
+            of hosts, starting and ending of hosts, etc.
           expected_event_types:
             - access
             - change
@@ -184,7 +187,9 @@
             - start
         - name: process
           description: >
-            Relating to the operation of software processes executing within operating systems on hosts. Use this category of events to visualize and analyze process starts, process parents, process relationships, etc.
+            Relating to the operation of software processes executing within operating
+            systems on hosts. Use this category of events to visualize and analyze process
+            starts, process parents, process relationships, etc.
           expected_event_types:
             - access
             - change
@@ -215,16 +220,17 @@
       example: user-password-change
 
     - name: outcome
-      level: extended
+      level: core
       type: keyword
-      short: The outcome of the event.
+      short: The outcome of the event. (Categorization Field)
       description: >
-        The outcome of the event.
+        This is one of four ECS Categorization Fields, and indicates the
+        lowest level in the ECS category hierarchy.
 
-        If the event describes an action, this fields contains the outcome of
-        that action.
+        `event.outcome` simply denotes whether the event represent a success or a failure.
+        Note that not all events will have an associated outcome. For example, this field is
+        generally not populated for metric events or events with `event.type:info`.
       example: success
-
       allowed_values:
         - name: failure
           description: >
@@ -246,11 +252,14 @@
     - name: type
       level: core
       type: keyword
-      short: Reserved for future usage.
+      short: Event type (Categorization Field)
       description: >
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
-        sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+        This is one of four ECS Categorization Fields, and indicates the
+        third level in the ECS category hierarchy.
 
+        `event.type` represents a categorization "sub-bucket" that, when used along with
+        the `event.category` field values, enables filtering events down to a level
+        appropriate for single visualization.
       allowed_values:
         - name: access
           description: >
@@ -258,24 +267,15 @@
             that indicate that something was accessed.
             Common examples include `event.category:database AND event.type:access`,
             or `event.category:file AND event.type:access`.
-            Note for file access, include both directory listings and file opens in this subcategory.
-            You can further distinguish access operations using the ECS `event.action` field.
-        - name: allowed
-          description: >
-            The allow event type is used for the subset of events within a category
-            that indicate that something was allowed.
-            Common examples include `event.category:network AND event.type:allow`
-            to indicate a network firewall event for which the firewall disposition
-            was to allow the connection to complete.
-            `event.category:network_flow AND event.type:allow` to indicate a network flow event
-            that is also a network firewall event for which the firewall disposition
-            was to allow the connection to complete.
+            Note for file access, both directory listings and file opens should be included
+            in this subcategory. You can further distinguish access operations using the ECS
+            `event.action` field.
         - name: change
           description: >
             The change event type is used for the subset of events within a category
             that indicate that something has changed. If semantics best describe an
             event as modified, then include them in this subcategory.
-            Common examples include `event.category:registry AND event.type:change`,
+            Common examples include `event.category:process AND event.type:change`,
             and `event.category:file AND event.type:change`.
             You can further distinguish change operations using the ECS `event.action` field.
         - name: creation
@@ -285,64 +285,38 @@
             A common example is `event.category:file AND event.type:create`.
         - name: deletion
           description: >
-            The delete event type is used for the subset of events within a category
+            The deletion event type is used for the subset of events within a category
             that indicate that something was deleted.
-            Common examples include `event.category:file AND event.type:delete`,
-            and `event.category:iam_user AND event.type:delete`,
-            to indicate that a user has been deleted from an Identity and Access Management system.
-        - name: denied
-          description: >
-            The deny event type is used for the subset of events within a category
-            that indicate that something was disallowed, blocked or denied.
-            Common examples include `event.category:network AND event.type:deny`
-            to indicate a network firewall event for which the firewall disposition
-            was to deny the connection to complete.
-            `event.category:network_flow AND event.type:deny` to indicate a network flow
-            event that is also a network firewall event for which the firewall disposition
-            was to deny the connection to complete.
-            Note that the `event.action` field can be used to further describe the
-            deny action with user-supplied values such as "drop", "reject", "block", "redirect", etc.
+            A common example is `event.category:file AND event.type:deletion`
+            to indicate that a file has been deleted.
         - name: end
           description: >
             The end event type is used for the subset of events within a category
             that indicate something has ended.
-            Common examples include `event.category:process AND event.type:end`,
-            and `event.category:network_flow AND event.type:end`
-            to indicate a flow record event that is sent at the completion of the network flow.
+            A common example is `event.category:process AND event.type:end`.
         - name: error
           description: >
             The error event type is used for the subset of events within a category
             that indicate or describe an error.
-            Common examples include `event.category:application AND event.type:error`
-            and `event.category:database AND event.type:error`.
+            A common example is `event.category:database AND event.type:error`.
             Note that pipeline errors that occur during the event ingestion process
-            should not use this `event.type` value.
-            Instead, they should use the `event.kind:pipeline_error`.
+            should not use this `event.type` value. Instead, they should use
+            `event.kind:pipeline_error`.
         - name: info
           description: >
             The info event type is used for the subset of events within a category
-            that indicate that they are purely informational, and don't report a state change, action.
-            For example, an initial run of a file integrity monitoring system (FIM)
-            where an agent reports all files under management would fall into the "info" subcategory.
-            Similarly, a dump of all current running processes (as opposed to reporting that process start/end)
-            would fall into the "info" subcategory.
-            Additional common examples include `event.category:registry AND event.type:info`,
-            and `event.category:intrusion_detection AND event.type:info`.
+            that indicate that they are purely informational, and don't report a state
+            change, or any type of action. For example, an initial run of a file integrity
+            monitoring system (FIM), where an agent reports all files under management,
+            would fall into the "info" subcategory. Similarly, an event containing a
+            dump of all currently running processes (as opposed to reporting that a process
+            started/ended) would fall into the "info" subcategory.
+            An additional common examples is `event.category:intrusion_detection AND event.type:info`.
         - name: installation
           description: >
-            The install event type is used for the subset of events within a category
+            The installation event type is used for the subset of events within a category
             that indicate that something was installed.
-            A common example is `event.category:package` AND `event.type:install`.
-        - name: protocol
-          description: >
-            The protocol event type is used for the subset of events within a category
-            that indicate that they contain protocol details or analysis.
-            Generally, network traffic and network flows that contain protocol
-            details will fall into this subcategory.
-            Common examples include `event.category:network AND event.type:protocol`,
-            and `event.category:network_flow AND event.type:protocol`.
-            Note for when the protocol subcategory is used, you can further distinguish
-            protocols using the ECS `network.protocol` field.
+            A common example is `event.category:package` AND `event.type:installed`.
         - name: start
           description: >
             The start event type is used for the subset of events within a category
diff --git a/scripts/helper.py b/scripts/helper.py
index 5ef3aeb1f2..0cc22a2b60 100644
--- a/scripts/helper.py
+++ b/scripts/helper.py
@@ -77,14 +77,19 @@ def clean_fields(fields, prefix, group):
 def clean_string_field(field, key):
     """Cleans a string field and creates an empty string for the field in case it does not exist
     """
-    if key in field.keys():
-        # Remove all spaces and newlines from beginning and end
-        field[key] = str(field[key]).strip()
-    else:
-        field[key] = ""
-
-    if "index" in field and field["index"] == False:
-        field["type"] = "(not indexed)"
+    try:
+        if key in field.keys():
+            # Remove all spaces and newlines from beginning and end
+            field[key] = str(field[key]).strip()
+        else:
+            field[key] = ""
+
+        if "index" in field and field["index"] == False:
+            field["type"] = "(not indexed)"
+    except UnicodeEncodeError:
+        # print("Problem with field {}, field details:".format(field[key]))
+        print(field)
+        raise
 
 
 def get_markdown_row(field, link, multi_field):

From 3db941dc86ae6206006f5e1f4c71e312d8ce87ad Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 09:42:27 -0500
Subject: [PATCH 13/27] Adjust mention of event type names to use the correct
 wording

---
 docs/field-values.asciidoc   |  8 ++++----
 generated/ecs/ecs_flat.yml   | 18 +++++++++---------
 generated/ecs/ecs_nested.yml | 17 +++++++++--------
 schemas/event.yml            | 12 ++++++------
 4 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 504a485b50..85b309577e 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -128,7 +128,7 @@ Events in this category are related to the challenge and response process in whi
 
 *Expected event types for category authentication:*
 
-allow, deny, info
+start, end, info
 
 
 [float]
@@ -174,7 +174,7 @@ change, creation, deletion, info
 [[ecs-event-category-host]]
 ==== host
 
-Events and metrics about hosts. Usually higher-level information about host activity from an external perspective. Different than operating system in the sense that host events are usually externally visible and independent from the OS. `event.category:host` is not meant to indicate events that are simply "happening on a host". Use this category to visualize and analyze inventories of hosts, starting and ending of hosts, etc.
+Events and metrics about hosts. Usually higher-level information about host activity from an external perspective. Different than operating system in the sense that host events are usually externally visible and independent from the OS. Note that `event.category:host` is not meant to indicate events that are simply "happening on a host". Use this category to visualize and analyze inventories of hosts, starting and ending of hosts, etc.
 
 
 
@@ -294,7 +294,7 @@ The change event type is used for the subset of events within a category that in
 [[ecs-event-type-creation]]
 ==== creation
 
-The create event type is used for the subset of events within a category that indicate that something was created. A common example is `event.category:file AND event.type:create`.
+The "creation" event type is used for the subset of events within a category that indicate that something was created. A common example is `event.category:file AND event.type:creation`.
 
 
 
@@ -339,7 +339,7 @@ The info event type is used for the subset of events within a category that indi
 [[ecs-event-type-installation]]
 ==== installation
 
-The installation event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:installed`.
+The installation event type is used for the subset of events within a category that indicate that something was installed. A common example is `event.category:package` AND `event.type:installation`.
 
 
 
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index 09ce92e862..f5060915d1 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1380,8 +1380,8 @@ event.category:
 
       '
     expected_event_types:
-    - allow
-    - deny
+    - start
+    - end
     - info
     name: authentication
   - description: 'The database category denotes events and metrics relating to a data
@@ -1425,9 +1425,9 @@ event.category:
   - description: 'Events and metrics about hosts. Usually higher-level information
       about host activity from an external perspective. Different than operating system
       in the sense that host events are usually externally visible and independent
-      from the OS. `event.category:host` is not meant to indicate events that are
-      simply "happening on a host". Use this category to visualize and analyze inventories
-      of hosts, starting and ending of hosts, etc.
+      from the OS. Note that `event.category:host` is not meant to indicate events
+      that are simply "happening on a host". Use this category to visualize and analyze
+      inventories of hosts, starting and ending of hosts, etc.
 
       '
     expected_event_types:
@@ -1868,9 +1868,9 @@ event.type:
 
       '
     name: change
-  - description: 'The create event type is used for the subset of events within a
-      category that indicate that something was created. A common example is `event.category:file
-      AND event.type:create`.
+  - description: 'The "creation" event type is used for the subset of events within
+      a category that indicate that something was created. A common example is `event.category:file
+      AND event.type:creation`.
 
       '
     name: creation
@@ -1907,7 +1907,7 @@ event.type:
     name: info
   - description: 'The installation event type is used for the subset of events within
       a category that indicate that something was installed. A common example is `event.category:package`
-      AND `event.type:installed`.
+      AND `event.type:installation`.
 
       '
     name: installation
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index 2c22cf7d93..b87c81d454 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1594,8 +1594,8 @@ event:
 
           '
         expected_event_types:
-        - allow
-        - deny
+        - start
+        - end
         - info
         name: authentication
       - description: 'The database category denotes events and metrics relating to
@@ -1639,9 +1639,10 @@ event:
       - description: 'Events and metrics about hosts. Usually higher-level information
           about host activity from an external perspective. Different than operating
           system in the sense that host events are usually externally visible and
-          independent from the OS. `event.category:host` is not meant to indicate
-          events that are simply "happening on a host". Use this category to visualize
-          and analyze inventories of hosts, starting and ending of hosts, etc.
+          independent from the OS. Note that `event.category:host` is not meant to
+          indicate events that are simply "happening on a host". Use this category
+          to visualize and analyze inventories of hosts, starting and ending of hosts,
+          etc.
 
           '
         expected_event_types:
@@ -2088,9 +2089,9 @@ event:
 
           '
         name: change
-      - description: 'The create event type is used for the subset of events within
+      - description: 'The "creation" event type is used for the subset of events within
           a category that indicate that something was created. A common example is
-          `event.category:file AND event.type:create`.
+          `event.category:file AND event.type:creation`.
 
           '
         name: creation
@@ -2129,7 +2130,7 @@ event:
         name: info
       - description: 'The installation event type is used for the subset of events
           within a category that indicate that something was installed. A common example
-          is `event.category:package` AND `event.type:installed`.
+          is `event.category:package` AND `event.type:installation`.
 
           '
         name: installation
diff --git a/schemas/event.yml b/schemas/event.yml
index 70f430bf48..8b18124934 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -105,8 +105,8 @@
             Visualize and analyze events in this category to look for unusual login activity,
             failed logins, etc.
           expected_event_types:
-            - allow
-            - deny
+            - start
+            - end
             - info
         - name: database
           description: >
@@ -148,7 +148,7 @@
             Events and metrics about hosts. Usually higher-level information about host
             activity from an external perspective. Different than operating system
             in the sense that host events are usually externally visible and independent from the OS.
-            `event.category:host` is not meant to indicate events that are simply
+            Note that `event.category:host` is not meant to indicate events that are simply
             "happening on a host". Use this category to visualize and analyze inventories
             of hosts, starting and ending of hosts, etc.
           expected_event_types:
@@ -280,9 +280,9 @@
             You can further distinguish change operations using the ECS `event.action` field.
         - name: creation
           description: >
-            The create event type is used for the subset of events within a category
+            The "creation" event type is used for the subset of events within a category
             that indicate that something was created.
-            A common example is `event.category:file AND event.type:create`.
+            A common example is `event.category:file AND event.type:creation`.
         - name: deletion
           description: >
             The deletion event type is used for the subset of events within a category
@@ -316,7 +316,7 @@
           description: >
             The installation event type is used for the subset of events within a category
             that indicate that something was installed.
-            A common example is `event.category:package` AND `event.type:installed`.
+            A common example is `event.category:package` AND `event.type:installation`.
         - name: start
           description: >
             The start event type is used for the subset of events within a category

From 6b5792aea9369fe90b86e48b7c81dd03e3383138 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 15:09:02 -0500
Subject: [PATCH 14/27] Add explicit mentions that event.category and
 event.type are array fields

---
 code/go/ecs/event.go           |  4 ++++
 docs/field-details.asciidoc    |  4 ++++
 docs/field-values.asciidoc     |  4 ++++
 generated/beats/fields.ecs.yml | 10 ++++++++--
 generated/ecs/ecs_flat.yml     | 10 ++++++++--
 generated/ecs/ecs_nested.yml   | 10 ++++++++--
 schemas/event.yml              |  6 ++++++
 7 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/code/go/ecs/event.go b/code/go/ecs/event.go
index 005a6d8376..39f413ae7c 100644
--- a/code/go/ecs/event.go
+++ b/code/go/ecs/event.go
@@ -57,6 +57,8 @@ type Event struct {
 	// example, filtering on `event.category:process` yields all events
 	// relating to process activity. This field is closely related to
 	// `event.type`, which is used as a subcategory.
+	// This field is an array. This will allow proper categorization of some
+	// events that fall in multiple categories.
 	Category string `ecs:"category"`
 
 	// The action captured by the event.
@@ -78,6 +80,8 @@ type Event struct {
 	// `event.type` represents a categorization "sub-bucket" that, when used
 	// along with the `event.category` field values, enables filtering events
 	// down to a level appropriate for single visualization.
+	// This field is an array. This will allow proper categorization of some
+	// events that fall in multiple event types.
 	Type string `ecs:"type"`
 
 	// Name of the module this data is coming from.
diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index 3a4321ef56..e88c02dd03 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1139,6 +1139,8 @@ example: `user-password-change`
 
 `event.category` represents the "big buckets" of ECS categories. For example, filtering on `event.category:process` yields all events relating to process activity. This field is closely related to `event.type`, which is used as a subcategory.
 
+This field is an array. This will allow proper categorization of some events that fall in multiple categories.
+
 type: keyword
 
 
@@ -1420,6 +1422,8 @@ type: keyword
 
 `event.type` represents a categorization "sub-bucket" that, when used along with the `event.category` field values, enables filtering events down to a level appropriate for single visualization.
 
+This field is an array. This will allow proper categorization of some events that fall in multiple event types.
+
 type: keyword
 
 
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 85b309577e..6bd1b70222 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -100,6 +100,8 @@ This is one of four ECS Categorization Fields, and indicates the second level in
 
 `event.category` represents the "big buckets" of ECS categories. For example, filtering on `event.category:process` yields all events relating to process activity. This field is closely related to `event.type`, which is used as a subcategory.
 
+This field is an array. This will allow proper categorization of some events that fall in multiple categories.
+
 NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
@@ -255,6 +257,8 @@ This is one of four ECS Categorization Fields, and indicates the third level in
 
 `event.type` represents a categorization "sub-bucket" that, when used along with the `event.category` field values, enables filtering events down to a level appropriate for single visualization.
 
+This field is an array. This will allow proper categorization of some events that fall in multiple event types.
+
 NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml
index c356b82e86..2cfda6cd52 100644
--- a/generated/beats/fields.ecs.yml
+++ b/generated/beats/fields.ecs.yml
@@ -951,7 +951,10 @@
         `event.category` represents the "big buckets" of ECS categories. For example,
         filtering on `event.category:process` yields all events relating to process
         activity. This field is closely related to `event.type`, which is used as
-        a subcategory.'
+        a subcategory.
+
+        This field is an array. This will allow proper categorization of some events
+        that fall in multiple categories.'
       example: authentication
     - name: code
       level: extended
@@ -1146,7 +1149,10 @@
 
         `event.type` represents a categorization "sub-bucket" that, when used along
         with the `event.category` field values, enables filtering events down to a
-        level appropriate for single visualization.'
+        level appropriate for single visualization.
+
+        This field is an array. This will allow proper categorization of some events
+        that fall in multiple event types.'
   - name: file
     title: File
     group: 2
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index f5060915d1..cd2c625c61 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1497,7 +1497,10 @@ event.category:
 
     `event.category` represents the "big buckets" of ECS categories. For example,
     filtering on `event.category:process` yields all events relating to process activity.
-    This field is closely related to `event.type`, which is used as a subcategory.'
+    This field is closely related to `event.type`, which is used as a subcategory.
+
+    This field is an array. This will allow proper categorization of some events that
+    fall in multiple categories.'
   example: authentication
   flat_name: event.category
   ignore_above: 1024
@@ -1923,7 +1926,10 @@ event.type:
 
     `event.type` represents a categorization "sub-bucket" that, when used along with
     the `event.category` field values, enables filtering events down to a level appropriate
-    for single visualization.'
+    for single visualization.
+
+    This field is an array. This will allow proper categorization of some events that
+    fall in multiple event types.'
   flat_name: event.type
   ignore_above: 1024
   level: core
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index b87c81d454..d6f0f3e17b 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1714,7 +1714,10 @@ event:
         `event.category` represents the "big buckets" of ECS categories. For example,
         filtering on `event.category:process` yields all events relating to process
         activity. This field is closely related to `event.type`, which is used as
-        a subcategory.'
+        a subcategory.
+
+        This field is an array. This will allow proper categorization of some events
+        that fall in multiple categories.'
       example: authentication
       flat_name: event.category
       ignore_above: 1024
@@ -2146,7 +2149,10 @@ event:
 
         `event.type` represents a categorization "sub-bucket" that, when used along
         with the `event.category` field values, enables filtering events down to a
-        level appropriate for single visualization.'
+        level appropriate for single visualization.
+
+        This field is an array. This will allow proper categorization of some events
+        that fall in multiple event types.'
       flat_name: event.type
       ignore_above: 1024
       level: core
diff --git a/schemas/event.yml b/schemas/event.yml
index 8b18124934..7b07611b79 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -95,6 +95,9 @@
         `event.category` represents the "big buckets" of ECS categories. For example,
         filtering on `event.category:process` yields all events relating to process activity.
         This field is closely related to `event.type`, which is used as a subcategory.
+
+        This field is an array. This will allow proper categorization of some events
+        that fall in multiple categories.
       example: authentication
       allowed_values:
         - name: authentication
@@ -260,6 +263,9 @@
         `event.type` represents a categorization "sub-bucket" that, when used along with
         the `event.category` field values, enables filtering events down to a level
         appropriate for single visualization.
+
+        This field is an array. This will allow proper categorization of some events
+        that fall in multiple event types.
       allowed_values:
         - name: access
           description: >

From 8db19a90d9c0a8501fe1179fd67106d39a7b78e6 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 15:25:19 -0500
Subject: [PATCH 15/27] Undo debugging code that didn't actually help

---
 scripts/helper.py | 21 ++++++++-------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/scripts/helper.py b/scripts/helper.py
index 0cc22a2b60..5ef3aeb1f2 100644
--- a/scripts/helper.py
+++ b/scripts/helper.py
@@ -77,19 +77,14 @@ def clean_fields(fields, prefix, group):
 def clean_string_field(field, key):
     """Cleans a string field and creates an empty string for the field in case it does not exist
     """
-    try:
-        if key in field.keys():
-            # Remove all spaces and newlines from beginning and end
-            field[key] = str(field[key]).strip()
-        else:
-            field[key] = ""
-
-        if "index" in field and field["index"] == False:
-            field["type"] = "(not indexed)"
-    except UnicodeEncodeError:
-        # print("Problem with field {}, field details:".format(field[key]))
-        print(field)
-        raise
+    if key in field.keys():
+        # Remove all spaces and newlines from beginning and end
+        field[key] = str(field[key]).strip()
+    else:
+        field[key] = ""
+
+    if "index" in field and field["index"] == False:
+        field["type"] = "(not indexed)"
 
 
 def get_markdown_row(field, link, multi_field):

From af6fcc52428b8976219cd2b5ce3ee639c996ab40 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 15:36:09 -0500
Subject: [PATCH 16/27] First try at a warning message at the top of the
 categorization section

---
 docs/field-values.asciidoc            | 9 ++++++++-
 scripts/generators/asciidoc_fields.py | 9 ++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 6bd1b70222..64978870b4 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -1,6 +1,13 @@
 
 [[ecs-category-field-values-reference]]
-== {ecs} Category Field Values
+== {ecs} Categorization Fields
+
+WARNING: This section of ECS is in beta and is subject to change. These allowed values
+are still under active development. Additional values will be published gradually,
+and some of the values or relationships described here may change.
+Users who want to provide feedback, or who want to have a look at
+upcoming allowed values can visit this public feedback document
+https://ela.st/ecs-categories-draft.
 
 At a high level, ECS provides fields to capture two types of event information:
 "Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 875731a3a2..fd0ffd125a 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -308,7 +308,14 @@ def page_field_values(ecs_flat):
 def values_section_header():
     return '''
 [[ecs-category-field-values-reference]]
-== {ecs} Category Field Values
+== {ecs} Categorization Fields
+
+WARNING: This section of ECS is in beta and is subject to change. These allowed values
+are still under active development. Additional values will be published gradually,
+and some of the values or relationships described here may change.
+Users who want to provide feedback, or who want to have a look at
+upcoming allowed values can visit this public feedback document
+https://ela.st/ecs-categories-draft.
 
 At a high level, ECS provides fields to capture two types of event information:
 "Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),

From 84a53f744b89e8e179aa391259d66360fcc5c763 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 16:04:14 -0500
Subject: [PATCH 17/27] TIL about the WARNING asciidoc label :-)

---
 docs/field-values.asciidoc            | 8 ++++----
 scripts/generators/asciidoc_fields.py | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 64978870b4..640fc68b9f 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -32,7 +32,7 @@ This is one of four ECS Categorization Fields, and indicates the highest level i
 
 `event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events.
 
-NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+WARNING: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
@@ -109,7 +109,7 @@ This is one of four ECS Categorization Fields, and indicates the second level in
 
 This field is an array. This will allow proper categorization of some events that fall in multiple categories.
 
-NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+WARNING: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
@@ -266,7 +266,7 @@ This is one of four ECS Categorization Fields, and indicates the third level in
 
 This field is an array. This will allow proper categorization of some events that fall in multiple event types.
 
-NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+WARNING: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
@@ -371,7 +371,7 @@ This is one of four ECS Categorization Fields, and indicates the lowest level in
 
 `event.outcome` simply denotes whether the event represent a success or a failure. Note that not all events will have an associated outcome. For example, this field is generally not populated for metric events or events with `event.type:info`.
 
-NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+WARNING: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index fd0ffd125a..0bc5407bd1 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -391,7 +391,7 @@ def field_values_page_template():
 
 {field_description}
 
-NOTE: *Warning*: Only allowed Categorization Field values listed in the ECS repository
+WARNING: Only allowed Categorization Field values listed in the ECS repository
 and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.

From e0d858aceeafcb19f0f053277ccdfdab1f0237ab Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 16:05:30 -0500
Subject: [PATCH 18/27] Use wording 'This value' & remove redundant sentences
 in event.kind values

---
 docs/field-values.asciidoc   |  6 +++---
 generated/ecs/ecs_flat.yml   | 19 +++++++++----------
 generated/ecs/ecs_nested.yml | 21 +++++++++------------
 schemas/event.yml            | 16 +++++++---------
 4 files changed, 28 insertions(+), 34 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 640fc68b9f..69a1d1a3b0 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -50,7 +50,7 @@ that will require subsequent breaking changes.
 [[ecs-event-kind-alert]]
 ==== alert
 
-`event.kind:alert` indicates an event that describes an alert. Alerts are often associated with detection rules. `event.kind:alert` is often populated for events coming from firewalls, intrusion detection systems, endpoint detection and response systems, etc. It is used to indicate that an alert was triggered.
+This value indicates an event that describes an alert, triggered by a detection rule. `event.kind:alert` is often populated for events coming from firewalls, intrusion detection systems, endpoint detection and response systems, and so on.
 
 
 
@@ -59,7 +59,7 @@ that will require subsequent breaking changes.
 [[ecs-event-kind-event]]
 ==== event
 
-`event.kind:event` is the most general and most common value of this field. It is used to represent events that indicate that something happened.
+This value is the most general and most common value of this field. It is used to represent events that indicate that something happened.
 
 
 
@@ -68,7 +68,7 @@ that will require subsequent breaking changes.
 [[ecs-event-kind-metric]]
 ==== metric
 
-Used to indicate that this event is a measurement taken at given point in time. Examples include CPU utilization, memory usage, or a vulnerability scan result. Events with `event.kind:metric` indicate that a measurement was taken.
+This value is used to indicate that this event is a numeric measurement was taken at given point in time. Examples include CPU utilization, memory usage, or a vulnerability scan result.
 
 
 
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index cd2c625c61..bbe261a09a 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1632,22 +1632,21 @@ event.ingested:
   type: date
 event.kind:
   allowed_values:
-  - description: '`event.kind:alert` indicates an event that describes an alert. Alerts
-      are often associated with detection rules. `event.kind:alert` is often populated
-      for events coming from firewalls, intrusion detection systems, endpoint detection
-      and response systems, etc. It is used to indicate that an alert was triggered.
+  - description: 'This value indicates an event that describes an alert, triggered
+      by a detection rule. `event.kind:alert` is often populated for events coming
+      from firewalls, intrusion detection systems, endpoint detection and response
+      systems, and so on.
 
       '
     name: alert
-  - description: '`event.kind:event` is the most general and most common value of
-      this field. It is used to represent events that indicate that something happened.
+  - description: 'This value is the most general and most common value of this field.
+      It is used to represent events that indicate that something happened.
 
       '
     name: event
-  - description: 'Used to indicate that this event is a measurement taken at given
-      point in time. Examples include CPU utilization, memory usage, or a vulnerability
-      scan result. Events with `event.kind:metric` indicate that a measurement was
-      taken.
+  - description: 'This value is used to indicate that this event is a numeric measurement
+      was taken at given point in time. Examples include CPU utilization, memory usage,
+      or a vulnerability scan result.
 
       '
     name: metric
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index d6f0f3e17b..fd451ad1a2 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1850,24 +1850,21 @@ event:
       type: date
     kind:
       allowed_values:
-      - description: '`event.kind:alert` indicates an event that describes an alert.
-          Alerts are often associated with detection rules. `event.kind:alert` is
-          often populated for events coming from firewalls, intrusion detection systems,
-          endpoint detection and response systems, etc. It is used to indicate that
-          an alert was triggered.
+      - description: 'This value indicates an event that describes an alert, triggered
+          by a detection rule. `event.kind:alert` is often populated for events coming
+          from firewalls, intrusion detection systems, endpoint detection and response
+          systems, and so on.
 
           '
         name: alert
-      - description: '`event.kind:event` is the most general and most common value
-          of this field. It is used to represent events that indicate that something
-          happened.
+      - description: 'This value is the most general and most common value of this
+          field. It is used to represent events that indicate that something happened.
 
           '
         name: event
-      - description: 'Used to indicate that this event is a measurement taken at given
-          point in time. Examples include CPU utilization, memory usage, or a vulnerability
-          scan result. Events with `event.kind:metric` indicate that a measurement
-          was taken.
+      - description: 'This value is used to indicate that this event is a numeric
+          measurement was taken at given point in time. Examples include CPU utilization,
+          memory usage, or a vulnerability scan result.
 
           '
         name: metric
diff --git a/schemas/event.yml b/schemas/event.yml
index 7b07611b79..5784c8961e 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -53,20 +53,18 @@
       allowed_values:
         - name: alert
           description: >
-            `event.kind:alert` indicates an event that describes an alert.
-            Alerts are often associated with detection rules. `event.kind:alert`
-            is often populated for events coming from firewalls, intrusion detection
-            systems, endpoint detection and response systems, etc.
-            It is used to indicate that an alert was triggered.
+            This value indicates an event that describes an alert, triggered by a detection rule.
+            `event.kind:alert` is often populated for events coming from firewalls,
+            intrusion detection systems, endpoint detection and response systems, and so on.
         - name: event
           description: >
-            `event.kind:event` is the most general and most common value of this
-            field. It is used to represent events that indicate that something happened.
+            This value is the most general and most common value of this field.
+            It is used to represent events that indicate that something happened.
         - name: metric
           description: >
-            Used to indicate that this event is a measurement taken at given point in time.
+            This value is used to indicate that this event is a numeric measurement
+            was taken at given point in time.
             Examples include CPU utilization, memory usage, or a vulnerability scan result.
-            Events with `event.kind:metric` indicate that a measurement was taken.
         - name: state
           description: >
             This value is similar to metric, except that the entity being measured does not

From 4443b5e3d1fd7b72eb803cc8e2efda78ea6b3502 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 16:16:06 -0500
Subject: [PATCH 19/27] Render value descriptions as asciidoc paragraphs

---
 scripts/generators/asciidoc_fields.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 0bc5407bd1..d6af8fa392 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -359,7 +359,7 @@ def render_field_values_page(field):
             body += field_value_template().format(
                 field_dashed_name=field['dashed_name'],
                 value_name=value_details['name'],
-                value_description=value_details['description'],
+                value_description=render_asciidoc_paragraphs(value_details['description']),
                 additional_details=additional_details
             )
     except UnicodeEncodeError:
@@ -387,7 +387,7 @@ def expected_event_types_template():
 def field_values_page_template():
     return '''
 [[ecs-allowed-values-{dashed_name}]]
-=== Allowed Values for {flat_name}
+=== ECS Categorization Field: {flat_name}
 
 {field_description}
 

From b4ffafd1b0f8c4171eee74b553b67d0397922282 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 16:16:21 -0500
Subject: [PATCH 20/27] Update the description of event.kind signal

---
 docs/field-values.asciidoc   | 40 +++++++++++++++++++++++++++++++-----
 generated/ecs/ecs_flat.yml   |  8 +++++---
 generated/ecs/ecs_nested.yml |  8 +++++---
 schemas/event.yml            |  8 +++++---
 4 files changed, 50 insertions(+), 14 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 69a1d1a3b0..6a3c624d19 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -26,7 +26,7 @@ ECS defines four Categorization Fields for this purpose, each of which falls und
 
 
 [[ecs-allowed-values-event-kind]]
-=== Allowed Values for event.kind
+=== ECS Categorization Field: event.kind
 
 This is one of four ECS Categorization Fields, and indicates the highest level in the ECS category hierarchy.
 
@@ -55,6 +55,7 @@ This value indicates an event that describes an alert, triggered by a detection
 
 
 
+
 [float]
 [[ecs-event-kind-event]]
 ==== event
@@ -64,6 +65,7 @@ This value is the most general and most common value of this field. It is used t
 
 
 
+
 [float]
 [[ecs-event-kind-metric]]
 ==== metric
@@ -73,6 +75,7 @@ This value is used to indicate that this event is a numeric measurement was take
 
 
 
+
 [float]
 [[ecs-event-kind-state]]
 ==== state
@@ -82,6 +85,7 @@ This value is similar to metric, except that the entity being measured does not
 
 
 
+
 [float]
 [[ecs-event-kind-pipeline_error]]
 ==== pipeline_error
@@ -91,17 +95,21 @@ This value indicates that an error occurred during the ingestion of this event,
 
 
 
+
 [float]
 [[ecs-event-kind-signal]]
 ==== signal
 
-The signal value is used by Elastic Kibana apps, such as SIEM, for app-specific purposes. `event.kind:signal` is thus reserved and should not be used for the ingestion of events into Elasticsearch.
+This value is used by the Elastic SIEM app to denote an Elasticsearch document that was created by a SIEM detection engine rule.
+
+Usage of this value is reserved, and pipelines should not populate `event.kind` with the value "signal".
+
 
 
 
 
 [[ecs-allowed-values-event-category]]
-=== Allowed Values for event.category
+=== ECS Categorization Field: event.category
 
 This is one of four ECS Categorization Fields, and indicates the second level in the ECS category hierarchy.
 
@@ -135,6 +143,7 @@ Events in this category are related to the challenge and response process in whi
 
 
 
+
 *Expected event types for category authentication:*
 
 start, end, info
@@ -148,6 +157,7 @@ The database category denotes events and metrics relating to a data storage and
 
 
 
+
 *Expected event types for category database:*
 
 access, change, info, error
@@ -161,6 +171,7 @@ Having to do operating system device drivers and similar software entities such
 
 
 
+
 *Expected event types for category driver:*
 
 change, end, info, start
@@ -174,6 +185,7 @@ Relating to a set of information that has been created on, or has existed on a f
 
 
 
+
 *Expected event types for category file:*
 
 change, creation, deletion, info
@@ -187,6 +199,7 @@ Events and metrics about hosts. Usually higher-level information about host acti
 
 
 
+
 *Expected event types for category host:*
 
 access, change, end, info, start
@@ -200,6 +213,7 @@ Relating to intrusion detections from IDS/IPS systems and functions, both networ
 
 
 
+
 *Expected event types for category intrusion_detection:*
 
 info
@@ -213,6 +227,7 @@ Malware detection events and alerts. Use this category to visualize and analyze
 
 
 
+
 *Expected event types for category malware:*
 
 info
@@ -226,6 +241,7 @@ Relating to software packages installed on hosts. Use this category to visualize
 
 
 
+
 *Expected event types for category package:*
 
 access, change, deletion, info, installation, start
@@ -239,6 +255,7 @@ Relating to the operation of software processes executing within operating syste
 
 
 
+
 *Expected event types for category process:*
 
 access, change, end, info, start
@@ -252,13 +269,14 @@ Relating to web server access. Use this category to create a dashboard of web se
 
 
 
+
 *Expected event types for category web:*
 
 access, error, info
 
 
 [[ecs-allowed-values-event-type]]
-=== Allowed Values for event.type
+=== ECS Categorization Field: event.type
 
 This is one of four ECS Categorization Fields, and indicates the third level in the ECS category hierarchy.
 
@@ -292,6 +310,7 @@ The access event type is used for the subset of events within a category that in
 
 
 
+
 [float]
 [[ecs-event-type-change]]
 ==== change
@@ -301,6 +320,7 @@ The change event type is used for the subset of events within a category that in
 
 
 
+
 [float]
 [[ecs-event-type-creation]]
 ==== creation
@@ -310,6 +330,7 @@ The "creation" event type is used for the subset of events within a category tha
 
 
 
+
 [float]
 [[ecs-event-type-deletion]]
 ==== deletion
@@ -319,6 +340,7 @@ The deletion event type is used for the subset of events within a category that
 
 
 
+
 [float]
 [[ecs-event-type-end]]
 ==== end
@@ -328,6 +350,7 @@ The end event type is used for the subset of events within a category that indic
 
 
 
+
 [float]
 [[ecs-event-type-error]]
 ==== error
@@ -337,6 +360,7 @@ The error event type is used for the subset of events within a category that ind
 
 
 
+
 [float]
 [[ecs-event-type-info]]
 ==== info
@@ -346,6 +370,7 @@ The info event type is used for the subset of events within a category that indi
 
 
 
+
 [float]
 [[ecs-event-type-installation]]
 ==== installation
@@ -355,6 +380,7 @@ The installation event type is used for the subset of events within a category t
 
 
 
+
 [float]
 [[ecs-event-type-start]]
 ==== start
@@ -364,8 +390,9 @@ The start event type is used for the subset of events within a category that ind
 
 
 
+
 [[ecs-allowed-values-event-outcome]]
-=== Allowed Values for event.outcome
+=== ECS Categorization Field: event.outcome
 
 This is one of four ECS Categorization Fields, and indicates the lowest level in the ECS category hierarchy.
 
@@ -391,6 +418,7 @@ Indicates that this event describes a failed result. A common example is `event.
 
 
 
+
 [float]
 [[ecs-event-outcome-success]]
 ==== success
@@ -400,6 +428,7 @@ Indicates that this event describes a successful result.  A common example is `e
 
 
 
+
 [float]
 [[ecs-event-outcome-unknown]]
 ==== unknown
@@ -408,3 +437,4 @@ Indicates that this event describes only an attempt for which the result is unkn
 
 
 
+
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index bbe261a09a..9a3c33c658 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1663,9 +1663,11 @@ event.kind:
 
       '
     name: pipeline_error
-  - description: 'The signal value is used by Elastic Kibana apps, such as SIEM, for
-      app-specific purposes. `event.kind:signal` is thus reserved and should not be
-      used for the ingestion of events into Elasticsearch.
+  - description: 'This value is used by the Elastic SIEM app to denote an Elasticsearch
+      document that was created by a SIEM detection engine rule.
+
+      Usage of this value is reserved, and pipelines should not populate `event.kind`
+      with the value "signal".
 
       '
     name: signal
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index fd451ad1a2..096ccfe0d4 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1881,9 +1881,11 @@ event:
 
           '
         name: pipeline_error
-      - description: 'The signal value is used by Elastic Kibana apps, such as SIEM,
-          for app-specific purposes. `event.kind:signal` is thus reserved and should
-          not be used for the ingestion of events into Elasticsearch.
+      - description: 'This value is used by the Elastic SIEM app to denote an Elasticsearch
+          document that was created by a SIEM detection engine rule.
+
+          Usage of this value is reserved, and pipelines should not populate `event.kind`
+          with the value "signal".
 
           '
         name: signal
diff --git a/schemas/event.yml b/schemas/event.yml
index 5784c8961e..d6e9229164 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -78,9 +78,11 @@
             `event.kind:pipeline_error` is often associated with parsing errors.
         - name: signal
           description: >
-            The signal value is used by Elastic Kibana apps, such as SIEM, for app-specific purposes.
-            `event.kind:signal` is thus reserved and should not be used for the ingestion
-            of events into Elasticsearch.
+            This value is used by the Elastic SIEM app to denote an Elasticsearch
+            document that was created by a SIEM detection engine rule.
+
+            Usage of this value is reserved, and pipelines should not populate
+            `event.kind` with the value "signal".
 
     - name: category
       level: core

From c5ba19dea1851e97ed4344e78b935798a8765b09 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 16:46:14 -0500
Subject: [PATCH 21/27] Replace TOC with 'Allowed Values'

---
 docs/field-values.asciidoc            | 8 ++++----
 scripts/generators/asciidoc_fields.py | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 6a3c624d19..68e2688093 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -37,7 +37,7 @@ and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
-*Table of Contents*
+*Allowed Values*
 
 * <<ecs-event-kind-alert,alert>>
 * <<ecs-event-kind-event,event>>
@@ -122,7 +122,7 @@ and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
-*Table of Contents*
+*Allowed Values*
 
 * <<ecs-event-category-authentication,authentication>>
 * <<ecs-event-category-database,database>>
@@ -289,7 +289,7 @@ and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
-*Table of Contents*
+*Allowed Values*
 
 * <<ecs-event-type-access,access>>
 * <<ecs-event-type-change,change>>
@@ -403,7 +403,7 @@ and official ECS documentation should be considered official.
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
-*Table of Contents*
+*Allowed Values*
 
 * <<ecs-event-outcome-failure,failure>>
 * <<ecs-event-outcome-success,success>>
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index d6af8fa392..8736aa096a 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -396,7 +396,7 @@ def field_values_page_template():
 Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
-*Table of Contents*
+*Allowed Values*
 
 '''
 

From 33171ef04a3d6e082d3db98380e0ffe4f5afe281 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 16 Dec 2019 16:48:51 -0500
Subject: [PATCH 22/27] Adjust a lot of the value definitions with some of the
 feedback.

---
 docs/field-values.asciidoc   | 30 ++++++++++++-----
 generated/ecs/ecs_flat.yml   | 61 +++++++++++++++++++++--------------
 generated/ecs/ecs_nested.yml | 62 ++++++++++++++++++++++--------------
 schemas/event.yml            | 51 ++++++++++++++++++-----------
 4 files changed, 129 insertions(+), 75 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 68e2688093..591a0d6c4c 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -50,7 +50,9 @@ that will require subsequent breaking changes.
 [[ecs-event-kind-alert]]
 ==== alert
 
-This value indicates an event that describes an alert, triggered by a detection rule. `event.kind:alert` is often populated for events coming from firewalls, intrusion detection systems, endpoint detection and response systems, and so on.
+This value indicates an event that describes an alert or notable event, triggered by a detection rule.
+
+`event.kind:alert` is often populated for events coming from firewalls, intrusion detection systems, endpoint detection and response systems, and so on.
 
 
 
@@ -60,7 +62,7 @@ This value indicates an event that describes an alert, triggered by a detection
 [[ecs-event-kind-event]]
 ==== event
 
-This value is the most general and most common value of this field. It is used to represent events that indicate that something happened.
+This value is the most general and most common value for this field. It is used to represent events that indicate that something happened.
 
 
 
@@ -70,7 +72,11 @@ This value is the most general and most common value of this field. It is used t
 [[ecs-event-kind-metric]]
 ==== metric
 
-This value is used to indicate that this event is a numeric measurement was taken at given point in time. Examples include CPU utilization, memory usage, or a vulnerability scan result.
+This value is used to indicate that this event that a numeric measurement was taken at given point in time.
+
+Examples include CPU utilization, memory usage, or a vulnerability scan result.
+
+Metric events are often collected on a predictable frequency, such as once every few seconds, or once a minute.
 
 
 
@@ -102,6 +108,8 @@ This value indicates that an error occurred during the ingestion of this event,
 
 This value is used by the Elastic SIEM app to denote an Elasticsearch document that was created by a SIEM detection engine rule.
 
+A signal will typically trigger a notification that something meaningful happened and should be investigated.
+
 Usage of this value is reserved, and pipelines should not populate `event.kind` with the value "signal".
 
 
@@ -139,7 +147,7 @@ that will require subsequent breaking changes.
 [[ecs-event-category-authentication]]
 ==== authentication
 
-Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows event logs, ssh logs, etc. Visualize and analyze events in this category to look for unusual login activity, failed logins, etc.
+Events in this category are related to the challenge and response process in which credentials are supplied and verified to allow the creation of a session. Common sources for these logs are Windows event logs and ssh logs. Visualize and analyze events in this category to look for failed logins, and other authentication-related activity.
 
 
 
@@ -167,7 +175,9 @@ access, change, info, error
 [[ecs-event-category-driver]]
 ==== driver
 
-Having to do operating system device drivers and similar software entities such as Windows drivers, kernel extensions, kernel modules, etc. Use events and metrics in this category to visualize and analyze driver-related activity and status on hosts.
+Events in the driver category have to do with operating system device drivers and similar software entities such as Windows drivers, kernel extensions, kernel modules, etc.
+
+Use events and metrics in this category to visualize and analyze driver-related activity and status on hosts.
 
 
 
@@ -195,7 +205,11 @@ change, creation, deletion, info
 [[ecs-event-category-host]]
 ==== host
 
-Events and metrics about hosts. Usually higher-level information about host activity from an external perspective. Different than operating system in the sense that host events are usually externally visible and independent from the OS. Note that `event.category:host` is not meant to indicate events that are simply "happening on a host". Use this category to visualize and analyze inventories of hosts, starting and ending of hosts, etc.
+Use this category to visualize and analyze information such as host inventory or host lifecycle events.
+
+Most of the events in this category can usually be observed from the outside, such as from a hypervisor or a control plane's point of view. Some can also be seen from within, such as "start" or "end".
+
+Note that this category is for information about hosts themselves; it is not meant to capture activity "happening on a host".
 
 
 
@@ -223,7 +237,7 @@ info
 [[ecs-event-category-malware]]
 ==== malware
 
-Malware detection events and alerts. Use this category to visualize and analyze malware detections from EDR/EPP systems such as Elastic Endpoint Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems and functions such as Palo Alto Networks threat and Wildfire logs.
+Malware detection events and alerts. Use this category to visualize and analyze malware detections from EDR/EPP systems such as Elastic Endpoint Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems such as Suricata, or other sources of malware-related events such as Palo Alto Networks threat logs and Wildfire logs.
 
 
 
@@ -251,7 +265,7 @@ access, change, deletion, info, installation, start
 [[ecs-event-category-process]]
 ==== process
 
-Relating to the operation of software processes executing within operating systems on hosts. Use this category of events to visualize and analyze process starts, process parents, process relationships, etc.
+Use this category of events to visualize and analyze process-specific information such as lifecycle events or process ancestry.
 
 
 
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index 9a3c33c658..fc0eafda50 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1374,9 +1374,9 @@ event.category:
   allowed_values:
   - description: 'Events in this category are related to the challenge and response
       process in which credentials are supplied and verified to allow the creation
-      of a session. Common sources for these logs are Windows event logs, ssh logs,
-      etc. Visualize and analyze events in this category to look for unusual login
-      activity, failed logins, etc.
+      of a session. Common sources for these logs are Windows event logs and ssh logs.
+      Visualize and analyze events in this category to look for failed logins, and
+      other authentication-related activity.
 
       '
     expected_event_types:
@@ -1397,9 +1397,11 @@ event.category:
     - info
     - error
     name: database
-  - description: 'Having to do operating system device drivers and similar software
-      entities such as Windows drivers, kernel extensions, kernel modules, etc. Use
-      events and metrics in this category to visualize and analyze driver-related
+  - description: 'Events in the driver category have to do with operating system device
+      drivers and similar software entities such as Windows drivers, kernel extensions,
+      kernel modules, etc.
+
+      Use events and metrics in this category to visualize and analyze driver-related
       activity and status on hosts.
 
       '
@@ -1422,12 +1424,15 @@ event.category:
     - deletion
     - info
     name: file
-  - description: 'Events and metrics about hosts. Usually higher-level information
-      about host activity from an external perspective. Different than operating system
-      in the sense that host events are usually externally visible and independent
-      from the OS. Note that `event.category:host` is not meant to indicate events
-      that are simply "happening on a host". Use this category to visualize and analyze
-      inventories of hosts, starting and ending of hosts, etc.
+  - description: 'Use this category to visualize and analyze information such as host
+      inventory or host lifecycle events.
+
+      Most of the events in this category can usually be observed from the outside,
+      such as from a hypervisor or a control plane''s point of view. Some can also
+      be seen from within, such as "start" or "end".
+
+      Note that this category is for information about hosts themselves; it is not
+      meant to capture activity "happening on a host".
 
       '
     expected_event_types:
@@ -1449,7 +1454,8 @@ event.category:
   - description: 'Malware detection events and alerts. Use this category to visualize
       and analyze malware detections from EDR/EPP systems such as Elastic Endpoint
       Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems
-      and functions such as Palo Alto Networks threat and Wildfire logs.
+      such as Suricata, or other sources of malware-related events such as Palo Alto
+      Networks threat logs and Wildfire logs.
 
       '
     expected_event_types:
@@ -1468,9 +1474,8 @@ event.category:
     - installation
     - start
     name: package
-  - description: 'Relating to the operation of software processes executing within
-      operating systems on hosts. Use this category of events to visualize and analyze
-      process starts, process parents, process relationships, etc.
+  - description: 'Use this category of events to visualize and analyze process-specific
+      information such as lifecycle events or process ancestry.
 
       '
     expected_event_types:
@@ -1632,21 +1637,26 @@ event.ingested:
   type: date
 event.kind:
   allowed_values:
-  - description: 'This value indicates an event that describes an alert, triggered
-      by a detection rule. `event.kind:alert` is often populated for events coming
-      from firewalls, intrusion detection systems, endpoint detection and response
-      systems, and so on.
+  - description: 'This value indicates an event that describes an alert or notable
+      event, triggered by a detection rule.
+
+      `event.kind:alert` is often populated for events coming from firewalls, intrusion
+      detection systems, endpoint detection and response systems, and so on.
 
       '
     name: alert
-  - description: 'This value is the most general and most common value of this field.
+  - description: 'This value is the most general and most common value for this field.
       It is used to represent events that indicate that something happened.
 
       '
     name: event
-  - description: 'This value is used to indicate that this event is a numeric measurement
-      was taken at given point in time. Examples include CPU utilization, memory usage,
-      or a vulnerability scan result.
+  - description: 'This value is used to indicate that this event that a numeric measurement
+      was taken at given point in time.
+
+      Examples include CPU utilization, memory usage, or a vulnerability scan result.
+
+      Metric events are often collected on a predictable frequency, such as once every
+      few seconds, or once a minute.
 
       '
     name: metric
@@ -1666,6 +1676,9 @@ event.kind:
   - description: 'This value is used by the Elastic SIEM app to denote an Elasticsearch
       document that was created by a SIEM detection engine rule.
 
+      A signal will typically trigger a notification that something meaningful happened
+      and should be investigated.
+
       Usage of this value is reserved, and pipelines should not populate `event.kind`
       with the value "signal".
 
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index 096ccfe0d4..33d9932a96 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1588,9 +1588,9 @@ event:
       allowed_values:
       - description: 'Events in this category are related to the challenge and response
           process in which credentials are supplied and verified to allow the creation
-          of a session. Common sources for these logs are Windows event logs, ssh
-          logs, etc. Visualize and analyze events in this category to look for unusual
-          login activity, failed logins, etc.
+          of a session. Common sources for these logs are Windows event logs and ssh
+          logs. Visualize and analyze events in this category to look for failed logins,
+          and other authentication-related activity.
 
           '
         expected_event_types:
@@ -1611,8 +1611,10 @@ event:
         - info
         - error
         name: database
-      - description: 'Having to do operating system device drivers and similar software
-          entities such as Windows drivers, kernel extensions, kernel modules, etc.
+      - description: 'Events in the driver category have to do with operating system
+          device drivers and similar software entities such as Windows drivers, kernel
+          extensions, kernel modules, etc.
+
           Use events and metrics in this category to visualize and analyze driver-related
           activity and status on hosts.
 
@@ -1636,13 +1638,15 @@ event:
         - deletion
         - info
         name: file
-      - description: 'Events and metrics about hosts. Usually higher-level information
-          about host activity from an external perspective. Different than operating
-          system in the sense that host events are usually externally visible and
-          independent from the OS. Note that `event.category:host` is not meant to
-          indicate events that are simply "happening on a host". Use this category
-          to visualize and analyze inventories of hosts, starting and ending of hosts,
-          etc.
+      - description: 'Use this category to visualize and analyze information such
+          as host inventory or host lifecycle events.
+
+          Most of the events in this category can usually be observed from the outside,
+          such as from a hypervisor or a control plane''s point of view. Some can
+          also be seen from within, such as "start" or "end".
+
+          Note that this category is for information about hosts themselves; it is
+          not meant to capture activity "happening on a host".
 
           '
         expected_event_types:
@@ -1664,7 +1668,8 @@ event:
       - description: 'Malware detection events and alerts. Use this category to visualize
           and analyze malware detections from EDR/EPP systems such as Elastic Endpoint
           Security, Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS
-          systems and functions such as Palo Alto Networks threat and Wildfire logs.
+          systems such as Suricata, or other sources of malware-related events such
+          as Palo Alto Networks threat logs and Wildfire logs.
 
           '
         expected_event_types:
@@ -1684,9 +1689,8 @@ event:
         - installation
         - start
         name: package
-      - description: 'Relating to the operation of software processes executing within
-          operating systems on hosts. Use this category of events to visualize and
-          analyze process starts, process parents, process relationships, etc.
+      - description: 'Use this category of events to visualize and analyze process-specific
+          information such as lifecycle events or process ancestry.
 
           '
         expected_event_types:
@@ -1850,21 +1854,28 @@ event:
       type: date
     kind:
       allowed_values:
-      - description: 'This value indicates an event that describes an alert, triggered
-          by a detection rule. `event.kind:alert` is often populated for events coming
-          from firewalls, intrusion detection systems, endpoint detection and response
-          systems, and so on.
+      - description: 'This value indicates an event that describes an alert or notable
+          event, triggered by a detection rule.
+
+          `event.kind:alert` is often populated for events coming from firewalls,
+          intrusion detection systems, endpoint detection and response systems, and
+          so on.
 
           '
         name: alert
-      - description: 'This value is the most general and most common value of this
+      - description: 'This value is the most general and most common value for this
           field. It is used to represent events that indicate that something happened.
 
           '
         name: event
-      - description: 'This value is used to indicate that this event is a numeric
-          measurement was taken at given point in time. Examples include CPU utilization,
-          memory usage, or a vulnerability scan result.
+      - description: 'This value is used to indicate that this event that a numeric
+          measurement was taken at given point in time.
+
+          Examples include CPU utilization, memory usage, or a vulnerability scan
+          result.
+
+          Metric events are often collected on a predictable frequency, such as once
+          every few seconds, or once a minute.
 
           '
         name: metric
@@ -1884,6 +1895,9 @@ event:
       - description: 'This value is used by the Elastic SIEM app to denote an Elasticsearch
           document that was created by a SIEM detection engine rule.
 
+          A signal will typically trigger a notification that something meaningful
+          happened and should be investigated.
+
           Usage of this value is reserved, and pipelines should not populate `event.kind`
           with the value "signal".
 
diff --git a/schemas/event.yml b/schemas/event.yml
index d6e9229164..ca2287dbc0 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -53,18 +53,24 @@
       allowed_values:
         - name: alert
           description: >
-            This value indicates an event that describes an alert, triggered by a detection rule.
+            This value indicates an event that describes an alert or notable event,
+            triggered by a detection rule.
+
             `event.kind:alert` is often populated for events coming from firewalls,
             intrusion detection systems, endpoint detection and response systems, and so on.
         - name: event
           description: >
-            This value is the most general and most common value of this field.
+            This value is the most general and most common value for this field.
             It is used to represent events that indicate that something happened.
         - name: metric
           description: >
-            This value is used to indicate that this event is a numeric measurement
+            This value is used to indicate that this event that a numeric measurement
             was taken at given point in time.
+
             Examples include CPU utilization, memory usage, or a vulnerability scan result.
+
+            Metric events are often collected on a predictable frequency, such as once
+            every few seconds, or once a minute.
         - name: state
           description: >
             This value is similar to metric, except that the entity being measured does not
@@ -81,6 +87,9 @@
             This value is used by the Elastic SIEM app to denote an Elasticsearch
             document that was created by a SIEM detection engine rule.
 
+            A signal will typically trigger a notification that something
+            meaningful happened and should be investigated.
+
             Usage of this value is reserved, and pipelines should not populate
             `event.kind` with the value "signal".
 
@@ -104,9 +113,9 @@
           description: >
             Events in this category are related to the challenge and response process
             in which credentials are supplied and verified to allow the creation of a session.
-            Common sources for these logs are Windows event logs, ssh logs, etc.
-            Visualize and analyze events in this category to look for unusual login activity,
-            failed logins, etc.
+            Common sources for these logs are Windows event logs and ssh logs.
+            Visualize and analyze events in this category to look for failed logins,
+            and other authentication-related activity.
           expected_event_types:
             - start
             - end
@@ -125,8 +134,9 @@
             - error
         - name: driver
           description: >
-            Having to do operating system device drivers and similar software entities
-            such as Windows drivers, kernel extensions, kernel modules, etc.
+            Events in the driver category have to do with operating system device drivers
+            and similar software entities such as Windows drivers, kernel extensions, kernel modules, etc.
+
             Use events and metrics in this category to visualize and analyze driver-related
             activity and status on hosts.
           expected_event_types:
@@ -148,12 +158,15 @@
             - info
         - name: host
           description: >
-            Events and metrics about hosts. Usually higher-level information about host
-            activity from an external perspective. Different than operating system
-            in the sense that host events are usually externally visible and independent from the OS.
-            Note that `event.category:host` is not meant to indicate events that are simply
-            "happening on a host". Use this category to visualize and analyze inventories
-            of hosts, starting and ending of hosts, etc.
+            Use this category to visualize and analyze information such as host inventory
+            or host lifecycle events.
+
+            Most of the events in this category can usually be observed from the outside,
+            such as from a hypervisor or a control plane's point of view. Some can also
+            be seen from within, such as "start" or "end".
+
+            Note that this category is for information about hosts themselves;
+            it is not meant to capture activity "happening on a host".
           expected_event_types:
             - access
             - change
@@ -172,8 +185,9 @@
           description: >
             Malware detection events and alerts. Use this category to visualize and analyze
             malware detections from EDR/EPP systems such as Elastic Endpoint Security,
-            Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems and
-            functions such as Palo Alto Networks threat and Wildfire logs.
+            Symantec Endpoint Protection, Crowdstrike, and network IDS/IPS systems
+            such as Suricata, or other sources of malware-related events such as
+            Palo Alto Networks threat logs and Wildfire logs.
           expected_event_types:
             - info
         - name: package
@@ -190,9 +204,8 @@
             - start
         - name: process
           description: >
-            Relating to the operation of software processes executing within operating
-            systems on hosts. Use this category of events to visualize and analyze process
-            starts, process parents, process relationships, etc.
+            Use this category of events to visualize and analyze process-specific
+            information such as lifecycle events or process ancestry.
           expected_event_types:
             - access
             - change

From 2ebba701a774786975222dd2484990ce6eef42b0 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <webmat@gmail.com>
Date: Tue, 17 Dec 2019 09:38:08 -0500
Subject: [PATCH 23/27] Adjust the 4 short definitions

Still not perfect, as they're all still self-referential. But at least the parens are gone.
---
 schemas/event.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/schemas/event.yml b/schemas/event.yml
index ca2287dbc0..94613b7c04 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -40,7 +40,7 @@
     - name: kind
       level: core
       type: keyword
-      short: The kind of the event. (Categorization Field)
+      short: The kind of the event. The highest categorization field in the hierarchy.
       description: >
         This is one of four ECS Categorization Fields, and indicates the
         highest level in the ECS category hierarchy.
@@ -96,7 +96,7 @@
     - name: category
       level: core
       type: keyword
-      short: Event category. (Categorization Field)
+      short: Event category. The second categorization field in the hierarchy.
       description: >
         This is one of four ECS Categorization Fields, and indicates the
         second level in the ECS category hierarchy.
@@ -238,7 +238,7 @@
     - name: outcome
       level: core
       type: keyword
-      short: The outcome of the event. (Categorization Field)
+      short: The outcome of the event. The lowest categorization field in the hierarchy.
       description: >
         This is one of four ECS Categorization Fields, and indicates the
         lowest level in the ECS category hierarchy.
@@ -268,7 +268,7 @@
     - name: type
       level: core
       type: keyword
-      short: Event type (Categorization Field)
+      short: Event type. The third categorization field in the hierarchy.
       description: >
         This is one of four ECS Categorization Fields, and indicates the
         third level in the ECS category hierarchy.

From 23bc882f0cef528fb844470f8981e184d0e9b05e Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Tue, 17 Dec 2019 09:56:11 -0500
Subject: [PATCH 24/27] Adjust 4 categorization page warnings, add note to
 leave fields empty

---
 docs/field-values.asciidoc            | 31 +++++++++++++++------------
 scripts/generators/asciidoc_fields.py | 13 ++++++-----
 2 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 591a0d6c4c..340b7bc0cf 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -11,9 +11,9 @@ https://ela.st/ecs-categories-draft.
 
 At a high level, ECS provides fields to capture two types of event information:
 "Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
-and "What it is." Categorization Fields hold the "What it is" information.
+and "What it is." categorization fields hold the "What it is" information.
 
-ECS defines four Categorization Fields for this purpose, each of which falls under the `event.*` field set.
+ECS defines four categorization fields for this purpose, each of which falls under the `event.*` field set.
 
 [float]
 [[ecs-category-fields]]
@@ -24,6 +24,9 @@ ECS defines four Categorization Fields for this purpose, each of which falls und
 * <<ecs-allowed-values-event-type,event.type>>
 * <<ecs-allowed-values-event-outcome,event.outcome>>
 
+NOTE: If your events don't match any of these categorization values, you should
+leave the fields empty. This will ensure you can start populating the fields
+once the appropriate categorization values are published, in a later release.
 
 [[ecs-allowed-values-event-kind]]
 === ECS Categorization Field: event.kind
@@ -32,9 +35,9 @@ This is one of four ECS Categorization Fields, and indicates the highest level i
 
 `event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events.
 
-WARNING: Only allowed Categorization Field values listed in the ECS repository
-and official ECS documentation should be considered official.
-Use of any other values may result in incompatible implementations
+WARNING: After the beta period for categorization, only the allowed categorization
+values listed in the ECS repository and official ECS documentation should be considered
+official. Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
 *Allowed Values*
@@ -125,9 +128,9 @@ This is one of four ECS Categorization Fields, and indicates the second level in
 
 This field is an array. This will allow proper categorization of some events that fall in multiple categories.
 
-WARNING: Only allowed Categorization Field values listed in the ECS repository
-and official ECS documentation should be considered official.
-Use of any other values may result in incompatible implementations
+WARNING: After the beta period for categorization, only the allowed categorization
+values listed in the ECS repository and official ECS documentation should be considered
+official. Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
 *Allowed Values*
@@ -298,9 +301,9 @@ This is one of four ECS Categorization Fields, and indicates the third level in
 
 This field is an array. This will allow proper categorization of some events that fall in multiple event types.
 
-WARNING: Only allowed Categorization Field values listed in the ECS repository
-and official ECS documentation should be considered official.
-Use of any other values may result in incompatible implementations
+WARNING: After the beta period for categorization, only the allowed categorization
+values listed in the ECS repository and official ECS documentation should be considered
+official. Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
 *Allowed Values*
@@ -412,9 +415,9 @@ This is one of four ECS Categorization Fields, and indicates the lowest level in
 
 `event.outcome` simply denotes whether the event represent a success or a failure. Note that not all events will have an associated outcome. For example, this field is generally not populated for metric events or events with `event.type:info`.
 
-WARNING: Only allowed Categorization Field values listed in the ECS repository
-and official ECS documentation should be considered official.
-Use of any other values may result in incompatible implementations
+WARNING: After the beta period for categorization, only the allowed categorization
+values listed in the ECS repository and official ECS documentation should be considered
+official. Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
 *Allowed Values*
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 8736aa096a..60a0027487 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -319,9 +319,9 @@ def values_section_header():
 
 At a high level, ECS provides fields to capture two types of event information:
 "Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
-and "What it is." Categorization Fields hold the "What it is" information.
+and "What it is." categorization fields hold the "What it is" information.
 
-ECS defines four Categorization Fields for this purpose, each of which falls under the `event.*` field set.
+ECS defines four categorization fields for this purpose, each of which falls under the `event.*` field set.
 
 [float]
 [[ecs-category-fields]]
@@ -332,6 +332,9 @@ def values_section_header():
 * <<ecs-allowed-values-event-type,event.type>>
 * <<ecs-allowed-values-event-outcome,event.outcome>>
 
+NOTE: If your events don't match any of these categorization values, you should
+leave the fields empty. This will ensure you can start populating the fields
+once the appropriate categorization values are published, in a later release.
 '''
 
 
@@ -391,9 +394,9 @@ def field_values_page_template():
 
 {field_description}
 
-WARNING: Only allowed Categorization Field values listed in the ECS repository
-and official ECS documentation should be considered official.
-Use of any other values may result in incompatible implementations
+WARNING: After the beta period for categorization, only the allowed categorization
+values listed in the ECS repository and official ECS documentation should be considered
+official. Use of any other values may result in incompatible implementations
 that will require subsequent breaking changes.
 
 *Allowed Values*

From 48daa1bd2c5693d90e78ee3df0427f72db65cf6e Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Tue, 17 Dec 2019 09:58:40 -0500
Subject: [PATCH 25/27] Rephrase the 'what it is' vs 'where it's from' text

---
 docs/field-values.asciidoc            | 5 +++--
 scripts/generators/asciidoc_fields.py | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 340b7bc0cf..6016dec3bc 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -9,9 +9,10 @@ Users who want to provide feedback, or who want to have a look at
 upcoming allowed values can visit this public feedback document
 https://ela.st/ecs-categories-draft.
 
-At a high level, ECS provides fields to capture two types of event information:
+At a high level, ECS provides fields to classify events in two different ways:
 "Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
-and "What it is." categorization fields hold the "What it is" information.
+and "What it is." The categorization fields hold the "What it is" information,
+independent of the source of the events.
 
 ECS defines four categorization fields for this purpose, each of which falls under the `event.*` field set.
 
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 60a0027487..e6747fa8bd 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -317,9 +317,10 @@ def values_section_header():
 upcoming allowed values can visit this public feedback document
 https://ela.st/ecs-categories-draft.
 
-At a high level, ECS provides fields to capture two types of event information:
+At a high level, ECS provides fields to classify events in two different ways:
 "Where it's from" (e.g., `event.module`, `event.dataset`, `agent.type`, `observer.type`, etc.),
-and "What it is." categorization fields hold the "What it is" information.
+and "What it is." The categorization fields hold the "What it is" information,
+independent of the source of the events.
 
 ECS defines four categorization fields for this purpose, each of which falls under the `event.*` field set.
 

From f3bae7b67951c0b119c5e8184dd39fc76f183dff Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Tue, 17 Dec 2019 10:06:38 -0500
Subject: [PATCH 26/27] Flesh out the event.kind description

---
 code/go/ecs/event.go           |  4 ++++
 docs/field-details.asciidoc    |  2 ++
 docs/field-values.asciidoc     |  2 ++
 generated/beats/fields.ecs.yml |  7 ++++++-
 generated/csv/fields.csv       |  8 ++++----
 generated/ecs/ecs_flat.yml     | 14 +++++++++-----
 generated/ecs/ecs_nested.yml   | 15 ++++++++++-----
 schemas/event.yml              |  4 ++++
 8 files changed, 41 insertions(+), 15 deletions(-)

diff --git a/code/go/ecs/event.go b/code/go/ecs/event.go
index 39f413ae7c..e9c5da72bc 100644
--- a/code/go/ecs/event.go
+++ b/code/go/ecs/event.go
@@ -49,6 +49,10 @@ type Event struct {
 	// the event contains, without being specific to the contents of the event.
 	// For example, values of this field distinguish alert events from metric
 	// events.
+	// The value of this field can be used to inform how these kinds of events
+	// should be handled. They may warrant different retention, different
+	// access control, it may also help understand whether the data coming in
+	// at a regular interval or not.
 	Kind string `ecs:"kind"`
 
 	// This is one of four ECS Categorization Fields, and indicates the second
diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index e88c02dd03..4b4996fb19 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -1267,6 +1267,8 @@ example: `2016-05-23 08:05:35.101000`
 
 `event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events.
 
+The value of this field can be used to inform how these kinds of events should be handled. They may warrant different retention, different access control, it may also help understand whether the data coming in at a regular interval or not.
+
 type: keyword
 
 
diff --git a/docs/field-values.asciidoc b/docs/field-values.asciidoc
index 6016dec3bc..6228129737 100644
--- a/docs/field-values.asciidoc
+++ b/docs/field-values.asciidoc
@@ -36,6 +36,8 @@ This is one of four ECS Categorization Fields, and indicates the highest level i
 
 `event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events.
 
+The value of this field can be used to inform how these kinds of events should be handled. They may warrant different retention, different access control, it may also help understand whether the data coming in at a regular interval or not.
+
 WARNING: After the beta period for categorization, only the allowed categorization
 values listed in the ECS repository and official ECS documentation should be considered
 official. Use of any other values may result in incompatible implementations
diff --git a/generated/beats/fields.ecs.yml b/generated/beats/fields.ecs.yml
index 2cfda6cd52..778801959a 100644
--- a/generated/beats/fields.ecs.yml
+++ b/generated/beats/fields.ecs.yml
@@ -1045,7 +1045,12 @@
 
         `event.kind` gives high-level information about what type of information the
         event contains, without being specific to the contents of the event. For example,
-        values of this field distinguish alert events from metric events.'
+        values of this field distinguish alert events from metric events.
+
+        The value of this field can be used to inform how these kinds of events should
+        be handled. They may warrant different retention, different access control,
+        it may also help understand whether the data coming in at a regular interval
+        or not.'
       example: alert
     - name: module
       level: core
diff --git a/generated/csv/fields.csv b/generated/csv/fields.csv
index 408f10d9a6..01e052c7f2 100644
--- a/generated/csv/fields.csv
+++ b/generated/csv/fields.csv
@@ -116,7 +116,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,false,error,error.stack_trace.text,text,extended,,The stack trace of this error in plain text.
 1.4.0-dev,true,error,error.type,keyword,extended,java.lang.NullPointerException,"The type of the error, for example the class name of the exception."
 1.4.0-dev,true,event,event.action,keyword,core,user-password-change,The action captured by the event.
-1.4.0-dev,true,event,event.category,keyword,core,authentication,Event category. (Categorization Field)
+1.4.0-dev,true,event,event.category,keyword,core,authentication,Event category. The second categorization field in the hierarchy.
 1.4.0-dev,true,event,event.code,keyword,extended,4648,Identification code for this event.
 1.4.0-dev,true,event,event.created,date,core,2016-05-23 08:05:34.857000,Time when the event was first read by an agent or by your pipeline.
 1.4.0-dev,true,event,event.dataset,keyword,core,apache.access,Name of the dataset.
@@ -125,10 +125,10 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,true,event,event.hash,keyword,extended,123456789012345678901234567890ABCD,Hash (perhaps logstash fingerprint) of raw field to be able to demonstrate log integrity.
 1.4.0-dev,true,event,event.id,keyword,core,8a4f500d,Unique ID to describe the event.
 1.4.0-dev,true,event,event.ingested,date,core,2016-05-23 08:05:35.101000,Timestamp when an event arrived in the central data store.
-1.4.0-dev,true,event,event.kind,keyword,core,alert,The kind of the event. (Categorization Field)
+1.4.0-dev,true,event,event.kind,keyword,core,alert,The kind of the event. The highest categorization field in the hierarchy.
 1.4.0-dev,true,event,event.module,keyword,core,apache,Name of the module this data is coming from.
 1.4.0-dev,false,event,event.original,keyword,core,Sep 19 08:26:10 host CEF:0&#124;Security&#124; threatmanager&#124;1.0&#124;100&#124; worm successfully stopped&#124;10&#124;src=10.0.0.1 dst=2.1.2.2spt=1232,Raw text message of entire event.
-1.4.0-dev,true,event,event.outcome,keyword,core,success,The outcome of the event. (Categorization Field)
+1.4.0-dev,true,event,event.outcome,keyword,core,success,The outcome of the event. The lowest categorization field in the hierarchy.
 1.4.0-dev,true,event,event.provider,keyword,extended,kernel,Source of the event.
 1.4.0-dev,true,event,event.risk_score,float,core,,Risk score or priority of the event (e.g. security solutions). Use your system's original value here.
 1.4.0-dev,true,event,event.risk_score_norm,float,extended,,Normalized risk score or priority of the event (0-100).
@@ -136,7 +136,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Example,Description
 1.4.0-dev,true,event,event.severity,long,core,7,Numeric severity of the event.
 1.4.0-dev,true,event,event.start,date,extended,,event.start contains the date when the event started or when the activity was first observed.
 1.4.0-dev,true,event,event.timezone,keyword,extended,,Event time zone.
-1.4.0-dev,true,event,event.type,keyword,core,,Event type (Categorization Field)
+1.4.0-dev,true,event,event.type,keyword,core,,Event type. The third categorization field in the hierarchy.
 1.4.0-dev,true,file,file.accessed,date,extended,,Last time the file was accessed.
 1.4.0-dev,true,file,file.attributes,keyword,extended,"[""readonly"", ""system""]",Array of file attributes.
 1.4.0-dev,true,file,file.created,date,extended,,File creation time.
diff --git a/generated/ecs/ecs_flat.yml b/generated/ecs/ecs_flat.yml
index fc0eafda50..a0cdc6f7c9 100644
--- a/generated/ecs/ecs_flat.yml
+++ b/generated/ecs/ecs_flat.yml
@@ -1512,7 +1512,7 @@ event.category:
   level: core
   name: category
   order: 3
-  short: Event category. (Categorization Field)
+  short: Event category. The second categorization field in the hierarchy.
   type: keyword
 event.code:
   dashed_name: event-code
@@ -1690,14 +1690,18 @@ event.kind:
 
     `event.kind` gives high-level information about what type of information the event
     contains, without being specific to the contents of the event. For example, values
-    of this field distinguish alert events from metric events.'
+    of this field distinguish alert events from metric events.
+
+    The value of this field can be used to inform how these kinds of events should
+    be handled. They may warrant different retention, different access control, it
+    may also help understand whether the data coming in at a regular interval or not.'
   example: alert
   flat_name: event.kind
   ignore_above: 1024
   level: core
   name: kind
   order: 2
-  short: The kind of the event. (Categorization Field)
+  short: The kind of the event. The highest categorization field in the hierarchy.
   type: keyword
 event.module:
   dashed_name: event-module
@@ -1765,7 +1769,7 @@ event.outcome:
   level: core
   name: outcome
   order: 5
-  short: The outcome of the event. (Categorization Field)
+  short: The outcome of the event. The lowest categorization field in the hierarchy.
   type: keyword
 event.provider:
   dashed_name: event-provider
@@ -1949,7 +1953,7 @@ event.type:
   level: core
   name: type
   order: 6
-  short: Event type (Categorization Field)
+  short: Event type. The third categorization field in the hierarchy.
   type: keyword
 file.accessed:
   dashed_name: file-accessed
diff --git a/generated/ecs/ecs_nested.yml b/generated/ecs/ecs_nested.yml
index 33d9932a96..f3231a4efb 100644
--- a/generated/ecs/ecs_nested.yml
+++ b/generated/ecs/ecs_nested.yml
@@ -1728,7 +1728,7 @@ event:
       level: core
       name: category
       order: 3
-      short: Event category. (Categorization Field)
+      short: Event category. The second categorization field in the hierarchy.
       type: keyword
     code:
       dashed_name: event-code
@@ -1909,14 +1909,19 @@ event:
 
         `event.kind` gives high-level information about what type of information the
         event contains, without being specific to the contents of the event. For example,
-        values of this field distinguish alert events from metric events.'
+        values of this field distinguish alert events from metric events.
+
+        The value of this field can be used to inform how these kinds of events should
+        be handled. They may warrant different retention, different access control,
+        it may also help understand whether the data coming in at a regular interval
+        or not.'
       example: alert
       flat_name: event.kind
       ignore_above: 1024
       level: core
       name: kind
       order: 2
-      short: The kind of the event. (Categorization Field)
+      short: The kind of the event. The highest categorization field in the hierarchy.
       type: keyword
     module:
       dashed_name: event-module
@@ -1984,7 +1989,7 @@ event:
       level: core
       name: outcome
       order: 5
-      short: The outcome of the event. (Categorization Field)
+      short: The outcome of the event. The lowest categorization field in the hierarchy.
       type: keyword
     provider:
       dashed_name: event-provider
@@ -2171,7 +2176,7 @@ event:
       level: core
       name: type
       order: 6
-      short: Event type (Categorization Field)
+      short: Event type. The third categorization field in the hierarchy.
       type: keyword
   group: 2
   name: event
diff --git a/schemas/event.yml b/schemas/event.yml
index 94613b7c04..323e99f509 100644
--- a/schemas/event.yml
+++ b/schemas/event.yml
@@ -49,6 +49,10 @@
         event contains, without being specific to the contents of the event.
         For example, values of this field distinguish alert events from
         metric events.
+
+        The value of this field can be used to inform how these kinds of events should be handled.
+        They may warrant different retention, different access control, it may also
+        help understand whether the data coming in at a regular interval or not.
       example: alert
       allowed_values:
         - name: alert

From 20ab515eb7092873e9cf8b6dac532f2550a63204 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Tue, 17 Dec 2019 10:17:42 -0500
Subject: [PATCH 27/27] Mention categorization in the changelog

---
 CHANGELOG.next.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md
index 003c135aca..76382090e1 100644
--- a/CHANGELOG.next.md
+++ b/CHANGELOG.next.md
@@ -22,8 +22,8 @@ Thanks, you're awesome :-) -->
 * Added `rule` fields. #665
 * Added default `text` analyzer as a multi-field to around 25 more fields. #680
 * Added `registry.*` fieldset for the Windows registry. #673
-* Publish initial list of allowed values for the reserved fields `event.kind`,
-  `event.category`, `event.type` and `event.outcome`. #684, #691, #692
+* Publish initial list of allowed values for the categorization fields (previously reserved)
+  `event.kind`, `event.category`, `event.type` and `event.outcome`. #684, #691, #692
 * Added `related.user` #694
 
 #### Improvements