Introducing doc section & code to publish the accepted values for res…

…erved fields (#684)

docs/field-details.asciidoc

@@ -1137,11 +1137,18 @@ example: `user-password-change`
 | event.category
 | 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. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution.
+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.
 
 type: keyword
 
-example: `user-management`
+
+*Important*: The field value must be one of the following:
+
+authentication{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}process
+
+To learn more about when to use which value, visit the page
+<<ecs-accepted-values-event-category,accepted values for event.category>>
+
 
 | core
 
@@ -1256,11 +1263,18 @@ example: `2016-05-23 08:05:35.101000`
 | event.kind
 | 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.  Examples are `event`, `state`, `alarm`. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution.
+This gives information about what type of information the event contains, without being specific to the contents of the event.
 
 type: keyword
 
-example: `state`
+
+*Important*: The field value must be one of the following:
+
+alert{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}event
+
+To learn more about when to use which value, visit the page
+<<ecs-accepted-values-event-kind,accepted values for event.kind>>
+
 
 | extended
 
@@ -1295,11 +1309,18 @@ example: `Sep 19 08:26:10 host CEF:0&#124;Security&#124; threatmanager&#124;1.0&
 | event.outcome
 | The outcome of the event.
 
-If the event describes an action, this fields contains the outcome of that action. Examples outcomes are `success` and `failure`. Warning: In future versions of ECS, we plan to provide a list of acceptable values for this field, please use with caution.
+If the event describes an action, this fields contains the outcome of that action.
 
 type: keyword
 
-example: `success`
+
+*Important*: The field value must be one of the following:
+
+success{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}failure
+
+To learn more about when to use which value, visit the page
+<<ecs-accepted-values-event-outcome,accepted values for event.outcome>>
+
 
 | extended
 
@@ -1395,13 +1416,18 @@ type: keyword
 // ===============================================================
 
 | event.type
-| Reserved for future usage.
-
-Please avoid using this field for user data.
+| Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
 type: keyword
 
 
+*Important*: The field value must be one of the following:
+
+start{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}end
+
+To learn more about when to use which value, visit the page
+<<ecs-accepted-values-event-type,accepted values for event.type>>
+
 
 | core
 

docs/field-values.asciidoc

@@ -0,0 +1,119 @@
+
+[[ecs-category-field-values-reference]]
+== {ecs} Category Field Values
+
+In ECS, certain fields are not meant to be populated by the event source, but...
+
+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-category-fields]]
+=== Category 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-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.
+
+[float]
+[[ecs-event-kind-alert]]
+==== alert
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-kind-event]]
+==== event
+
+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-authentication]]
+==== authentication
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+*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
+
+
+
+[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.
+
+
+
+*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
+
+
+
+[[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
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[float]
+[[ecs-event-type-end]]
+==== end
+
+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
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+
+
+
+[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.
+
+
+

docs/index.asciidoc

@@ -57,5 +57,6 @@ Guidelines].
 
 include::using.asciidoc[]
 include::fields.asciidoc[]
+include::field-values.asciidoc[]
 include::migrating.asciidoc[]
 include::additional.asciidoc[]

generated/beats/fields.ecs.yml

@@ -949,8 +949,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. Warning: In future versions of ECS, we plan to provide a
-        list of acceptable values for this field, please use with caution.'
+        multiple actions.'
       example: user-management
     - name: code
       level: extended
@@ -1039,10 +1038,8 @@
       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.  Examples are `event`,
-        `state`, `alarm`. Warning: In future versions of ECS, we plan to provide a
-        list of acceptable values for this field, please use with caution.'
-      example: state
+        without being specific to the contents of the event.'
+      example: event
     - name: module
       level: core
       type: keyword
@@ -1070,9 +1067,7 @@
       description: 'The outcome of the event.
 
         If the event describes an action, this fields contains the outcome of that
-        action. Examples outcomes are `success` and `failure`. Warning: In future
-        versions of ECS, we plan to provide a list of acceptable values for this field,
-        please use with caution.'
+        action.'
       example: success
     - name: provider
       level: extended
@@ -1140,9 +1135,8 @@
       level: core
       type: keyword
       ignore_above: 1024
-      description: 'Reserved for future usage.
-
-        Please avoid using this field for user data.'
+      description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+        eiusmod tempor incididunt ut labore et dolore magna aliqua.
   - name: file
     title: File
     group: 2

generated/csv/fields.csv

@@ -125,7 +125,7 @@ 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,state,The kind of the event.
+1.4.0-dev,true,event,event.kind,keyword,extended,event,The kind of the event.
 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|Security| threatmanager|1.0|100| worm successfully stopped|10|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.