[Docs]Adds timeline schema and API (#50)

* adds timeline schema

* starts create timeline endpoint

* create timeline cont

* finishes api

* corrections after review

* UUID for template ID

docs/siem/index.asciidoc

@@ -1,13 +1,3 @@
-// :doctype:      book
-// :siem-soln:    Elastic Security
-// :siem-app:     Elastic Security app
-// :siem-ui:      Elastic Security UI
-// :ml-dir:       {stack-docs-root}/docs/en/stack/ml
-// :sn: ServiceNow
-
-// Removed for merging with unified security docs
-// = SIEM Guide
-
 include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
 
 include::{docs-root}/shared/attributes.asciidoc[]
@@ -23,7 +13,3 @@ include::detections/machine-learning/ml-index.asciidoc[]
 include::detections/detections-index.asciidoc[]
 
 include::cases/cases-index.asciidoc[]
-
-// include::siem-apis.asciidoc[]
-
-// include::reference/ref-index.asciidoc[]

docs/siem/reference/timeline-schema.asciidoc

@@ -2,3 +2,255 @@
 [role="xpack"]
 == Timeline schema
 
+The Timeline schema lists all the JSON fields and objects required to create a
+Timeline or a Timeline template using the Create timeline API.
+
+IMPORTANT: All column, dropzone, and filter fields must be
+{ecs-ref}[ECS fields].
+
+This screenshot maps the Timeline UI components to their JSON objects:
+
+[role="screenshot"]
+image::images/timeline-object-ui.png[]
+
+. <<timeline-object-title, Title>> (`title`)
+. <<timeline-object-desc, Description>> (`description`)
+. <<timeline-object-global-notes, Global notes>> (`globalNotes`)
+. <<timeline-object-daterange, Time filter>> (`dateRange`)
+. <<timeline-object-dropzone, Dropzone>> (each clause is contained in
+its own `dataProviders` object)
+. <<timeline-object-kqlmode, KQL bar mode>> (`kqlMode`)
+. <<timeline-object-kqlquery, KQL bar query>> (`kqlQuery`)
+. <<timeline-object-eventtype, Event types included in Timeline results>>
+(`eventType`)
+. <<timeline-object-filters, Additional filters>> (`filters`)
+. <<timeline-object-columns, Column headers>> (`columns`)
+. <<timeline-object-event-notes, Event-specific notes>> (`eventNotes`)
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|[[timeline-object-columns]]`columns` |<<col-obj, columns[]>> |The timeline's
+columns.
+|`created` |Float |The time the timeline was created, using a 13-digit Epoch
+timestamp.
+|`createdBy` |String |The user who created the timeline.
+|[[timeline-object-dropzone]]`dataProviders`
+|<<dataProvider-obj, dataProviders[]>> |Object containing dropzone query
+clauses.
+|[[timeline-object-daterange]]`dateRange` |dateRange a|The timeline's search
+period:
+
+* `end`: The time up to which events are searched, using a 13-digit Epoch
+timestamp.
+* `start`: The time from which events are searched, using a 13-digit Epoch
+timestamp.
+
+|[[timeline-object-desc]]`description` |String |The timeline's description.
+|[[timeline-object-event-notes]]`eventNotes` |<<eventNotes-obj, eventNotes[]>>
+|Notes added to specific events in the timeline.
+|[[timeline-object-eventtype]]`eventType` |String a|Event types displayed in
+the timeline, which can be:
+
+* `all`: all events
+* `raw`: raw events only
+* `signal`: signals only
+
+|`favorite` |<<favorite-obj, favorite[]>> |Indicates when and who marked a
+timeline as a favorite.
+|[[timeline-object-filters]]`filters` |<<filters-obj, filters[]>> |Filters used
+in addition to the dropzone query.
+|[[timeline-object-global-notes]]`globalNotes`
+|<<globalNotes-obj, globalNotes[]>> |Global notes added to the timeline.
+|[[timeline-object-kqlmode]]`kqlMode` |String a|Indicates whether the KQL bar
+filters the dropzone query results or searches for additional results, where:
+
+* `filter`: filters dropzone query results
+* `search`: displays additional search results
+
+|[[timeline-object-kqlquery]]`kqlQuery` |<<kqlQuery-obj, kqlQuery>> |KQL bar
+query.
+|`pinnedEventIds` |pinnedEventIds[] |IDs of events pinned to the timeline's
+search results.
+|`savedObjectId` |String |The timeline's saved object ID.
+|`savedQueryId` |String |If used, the saved query ID used to filter or search
+dropzone query results.
+|`sort` |sort a|Object indicating how rows are sorted in the timeline's grid:
+
+* `columnId` (string): The ID of the column used to sort results.
+* `sortDirection` (string): The sort direction, which can be either `desc` or
+`asc`.
+
+|`templateTimelineId` |String a| A unique ID (UUID) for Timeline templates. For
+timelines, the value is `null`.
+|`templateTimelineVersion` |Integer |Timeline template version number. For
+timelines, the value is `null`.
+// When creating timeline template via import, can just specify it to 1.
+// We use this version to avoid template timeline to be overwrite when updating
+// via import.
+// We take every positive int given from user as long as it is grater than
+// current value.
+|[[timeline-object-typeField]]`timelineType` |String a|Indicates whether the
+timeline is a template or not, where:
+
+* `default`: Indicates a timeline used to actively investigate events.
+* `template`: Indicates a timeline template used when detection rule alerts are
+investigated in Timeline.
+
+|[[timeline-object-title]]`title` |String |The timeline's title.
+|`updated` |Float |The last time the timeline was updated, using a
+13-digit Epoch timestamp.
+|`updatedBy` |String |The user who last updated the timeline.
+|`version` |String |The timeline's version.
+|==============================================
+
+[[col-obj]]
+[discrete]
+==== columns object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`aggregatable` |Boolean |Indicates whether the field can be aggregated across
+all indices (used to sort columns in the UI).  
+|`category` |String |The ECS field set to which the field belongs.
+|`description` |String |UI column field description tooltip.
+|`example` |String |UI column field example tooltip.
+|`indexes` |String |Security indices in which the field exists and has the same
+{es} type. `null` when all the security indices have the field with the same
+type.
+|`id` |String |ECS field name, displayed as the column header in the UI.
+// |`searchable` |Boolean |Indicates whether the field is indexed for search on
+// all indices.
+|`type` |String |The field's type.
+|==============================================
+
+[[dataProvider-obj]]
+[discrete]
+==== dataProviders object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`and` |dataProviders[] |Array containing dropzone query clauses using `AND`
+logic.
+|`enabled` |Boolean |Indicates if the dropzone query clause is enabled.
+|`excluded` |Boolean |Indicates if the dropzone query clause uses `NOT` logic.
+|`id` |String |The dropzone query clause's unique ID.
+|`name` |String |The dropzone query clause's name (the clause's value
+when timelines are exported from the UI).
+|`queryMatch` |queryMatch a|The dropzone query clause:
+
+* `field` (string): The field used to search SIEM indices.
+* `operator` (string): The clause's operator, which can be:
+** `:` - The `field` has the specified `value`.
+** `:*` - The field exists.
+
+* `value` (string): The field's value used to match results.
+
+|==============================================
+
+[[eventNotes-obj]]
+[discrete]
+==== eventNotes object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`created` |Float |The time the note was created, using a 13-digit Epoch
+timestamp.
+|`createdBy` |String |The user who added the note.
+|`eventId` |String |The ID of the event to which the note was added.
+|`note` |String |The note's text.
+|`noteId` |String |The note's ID
+|`timelineId` |String |The ID of the timeline to which the note was added.
+|`updated` |Float |The last time the note was updated, using a
+13-digit Epoch timestamp.
+|`updatedBy` |String |The user who last updated the note.
+|`version` |String |The note's version.
+|==============================================
+
+[[favorite-obj]]
+[discrete]
+==== favorite object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`favoriteDate` |Float |The time the timeline was marked as a favorite, using a
+13-digit Epoch timestamp.
+|`fullName` |String |The full name of the user who marked the timeline as
+a favorite.
+|`keySearch` |String |`userName` encoded in Base64.
+|`userName` |String |The {kib} username of the user who marked the
+timeline as a favorite.
+|==============================================
+
+[[filters-obj]]
+[discrete]
+==== filters object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`exists` |String |{ref}/query-dsl-exists-query.html[Exists term query] for the
+specified field (`null` when undefined). For example, `{"field":"user.name"}`.
+|`meta` |meta a|Filter details:
+
+* `alias` (string): UI filter name.
+* `disabled` (boolean): Indicates if the filter is disabled.
+* `key`(string): Field name or unique string ID.
+* `negate` (boolean): Indicates if the filter query clause uses `NOT` logic.
+* `params` (string): Value of `phrase` filter types.
+* `type` (string): Type of filter. For example, `exists` and `range`. For more
+information about filtering, see {ref}/query-dsl.html[Query DSL].
+
+|`match_all` |String |{ref}/query-dsl-match-all-query.html[Match all term query]
+for the specified field (`null` when undefined). 
+|`query` |String |{ref}/query-dsl.html[DSL query] (`null` when undefined). For
+example, `{"match_phrase":{"ecs.version":"1.4.0"}}`.
+|`range` |String |{ref}/query-dsl-range-query.html[Range query] (`null` when
+undefined). For example, `{"@timestamp":{"gte":"now-1d","lt":"now"}}"`.
+|==============================================
+
+[[globalNotes-obj]]
+[discrete]
+==== globalNotes object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`created` |Float |The time the note was created, using a 13-digit Epoch
+timestamp.
+|`createdBy` |String |The user who added the note.
+|`note` |String |The note's text.
+|`noteId` |String |The note's ID
+|`timelineId` |String |The ID of the timeline to which the note was added.
+|`updated` |Float |The last time the note was updated, using a
+13-digit Epoch timestamp.
+|`updatedBy` |String |The user who last updated the note.
+|`version` |String |The note's version.
+|==============================================
+
+[[kqlQuery-obj]]
+[discrete]
+==== kqlQuery object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|`filterQuery` |filterQuery a|Object containing query details:
+
+* `kuery`: Object containing the query's clauses and type:
+** `expression`(string): The query's clauses.
+** `kind` (string): The type of query, which can be `kuery` or `lucene`.
+* `serializedQuery` (string): The query represented in JSON format.
+|==============================================