Data Formats
Items in KronoGraph such as entities, events or time series charts are described as plain JavaScript objects whose properties configure the appearance of each item. Events also describe their relationship to other entities. See the Timeline Items Docs for more details.
The formats below describe the data structures used to define items in the timeline.
Defines an annotation drawn on specified events and entities.
string | null
default: null The annotation body border color, or null for no border.
'rectangle' | 'roundrect'
default: 'roundrect' The annotation body border shape.
'solid' | 'dashed'
default: 'solid' The annotation body border line style.
number
default: 1 The width of the border for the annotation body.
object The style of the connector between the annotation and the annotated subject(s).
string
default: '#fff' The color of the connector line and container.
'none' | 'rectangle' | 'roundrect'
default: 'roundrect' The shape of the container to draw around the subject(s).
'solid' | 'dashed'
default: 'solid' The style of the connector line and container.
boolean
default: false Whether to merge multiple containers together.
'arrow' | 'dot' | 'circle' | 'none'
default: 'circle' The decoration shown at the subject end of the connector line.
number
default: 1 The width of the connector line and container.
string | null
default: '#33353e' The annotation body fill color, or null for no fill.
number
default: 16 The font size of the annotation body label.
label
required string The text for the annotation body.
string
default: '#fff' The color of the text annotation body label.
object The position of the annotation relative to the subject(s) it annotates.
string | number
default: 'top' The angle at which the annotation is positioned relative to its subject(s). Use a compass point value ( 'n', 'ne' etc.) or integer degrees clockwise from the top. Use 'top' or 'bottom' to position the annotation in the top or bottom rail.
number
default: 10 Distance between the annotation and its subject(s) in pixels.
subject
required string | EntityRangeSubject | (string | EntityRangeSubject)[] The subject or subjects to annotate: string ids for events or EntityRangeSubject objects for ranges of entity activity.
An object describing the annotation body position in view coordinates, which are measured in pixels relative to the top left corner of the timeline.
Options to set the drag.
type
required 'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null The type of drag:
- 'annotationScrollBar' - Scrolls the text of an annotation.
- 'labelAreaWidth' - Changes the width of the entity label area.
- 'lensScrollbar' - Scrolls through lens view.
- 'marqueeRange' - Draws a marquee range. On
drag-end, the default action is to zoom into the selected range. - 'marqueeSelection' - Draws a selection marquee.
- 'moveAnnotation' - Moves the body of an annotation.
- 'pan' - Pans the timeline.
- null - No dragging behavior.
Defines an entity, an item drawn horizontally along the timeline.
string The color of the entity.
any Property for storing custom data for the entity.
boolean Controls whether the entity line outside the range of its associated events should be faded.
string The text for the entity's label. If not specified, the entity's id is used. See also truncateLabelsAt.
string The color of the entity labels.
number The width (thickness) of the entity's timeline in pixels. When using expanded rows, only applies to rows, not sub-rows.
string
default: 'default' The type of the entity as declared in the entityTypes object. If not specified, the 'default' type is used. See the Entity Types docs.
An object describing the entity position in view coordinates, which are measured in pixels relative to the top left corner of the timeline.
x1
required number The x position at the left edge of the row containing the entity.
x2
required number The x value at the right edge of the row containing the entity.
y1
required number The y value at the top of the row containing the entity.
y2
required number The y value at the bottom of the row containing the entity.
An object identifying a time range to annotate for a specified entity or entities.
Specifies the properties of an entity that can be overridden with overrideStyles.
string The color of the entity.
boolean Controls whether the entity line outside the range of its associated events should be faded.
string The color of the entity labels.
number The width (thickness) of the entity's timeline in pixels. When using expanded rows, only applies to rows, not sub-rows.
Specifies the appearance and behavior of types of entities.
string
default: 'default' The name of the entity type that this type inherits any unspecified properties from.
string
default: '#3ebd93' The color of entities of this type.
boolean
default: false Controls if entity lines outside their range of associated events are faded.
The glyph drawn for the label of entities of this type. If false or not specified, no glyph is drawn.
string[] An array specifying the names of properties on the entity's data object used for grouping entities of this type, innermost first. For example: ['city', 'state', 'country'] will group by city, then state, then country.
string
default: '#e5e8eb' The label color for entities of this type.
number
default: 1 The line width in pixels for entities of this type.
number A number specifying the display order for entities of this type. Entity types with lower values are placed higher. Entities with no specified order appear at the bottom.
The glyph drawn in the label for a group of entities of this type. If false or not specified, no glyph is drawn.
string | false The text used to label a group of entities of this type. If false, no label is shown. If not specified, the type name is used.
Defines an event, an item drawn on or between entities at a particular time.
string | 'from' | 'to' | 'entity' | 'inverse' The color of the event. Can be either a single color or one of the following values. Also applies to events with more than 2 entities.
- 'from' - Event takes its color from its first 'from' entity.
- 'to' - Event takes its color from its first 'to' entity.
- 'entity' - Event has a color gradient matching the color of each entity it joins with.
- 'inverse' - Event has a color gradient with each end matching the opposite entity's color. For events with more than 2 entities, the color gradient follows the 'from' coloring behavior.
any Property for storing custom data for the event.
entityIds
required string[] | { from: string | string[]; to?: string | string[] } The ids of entities connected to the event. An event must have at least one connected entity. entityIds may be provided as:
- An array of entity ids, where the event is directed from the first entity to the rest of the entities.
- An object with
fromandtoproperties which determine the event direction in relation to each entity. These properties can be either a single string entity id, or an array of entity ids.
number | string The width of the event line.
- If a number, is used directly as the line width in px units.
- If a string, the value of the corresponding property on the event's
dataobject is used instead, and an adjustment is applied to these values to even the distribution of the line widths throughout the dataset. - If not specified, the value in the event's type is used.
boolean Controls if arrows on the event are shown. If not specified, the value in the event's type is used.
Either a Date in local time, a millisecond number in UTC, or a TimeRange object.
number The number of nanoseconds to add to the time value.
string The type of the event as declared in the eventTypes object.
A dictionary detailing which modifier keys were pressed when the event occurred.
boolean If an alt key was held down when the event occurred.
boolean If a consistent control key was held down when the event occurred. cmd key on MacOS, ctrl key on other OSs.
boolean If a control key was held down when the event occurred.
boolean If the meta key was held down when the event occurred.
boolean If a shift key was held down when the event occurred.
An object describing the event position in view coordinates, which are measured in pixels relative to the top left corner of the timeline.
x1
required number The x position corresponding to the start time of the event.
x2
required number The x position corresponding to the end time of the event.
y1
required number The y value of the top of the event.
y2
required number The y value of the bottom of the event.
wrappedSegments
required { x1: number; x2: number }[] This property only applies when using Scale Wrapping. An array containing the x positions corresponding to the start and end times for each segment, ordered from left to right as they appear on the timeline. For most events, there is only one segment, so can be ignored.
Specifies the properties of an event that can be overridden with overrideStyles.
string | 'from' | 'to' | 'entity' | 'inverse' The color of the event. Can be either a single color or one of the following values. Also applies to events with more than 2 entities.
- 'from' - Event takes its color from its first 'from' entity.
- 'to' - Event takes its color from its first 'to' entity.
- 'entity' - Event has a color gradient matching the color of each entity it joins with.
- 'inverse' - Event has a color gradient with each end matching the opposite entity's color. For events with more than 2 entities, the color gradient follows the 'from' coloring behavior.
number The width of the event line in pixels.
boolean Controls if arrows on the event are shown. If not specified, the value in the event's type is used.
string The type of the event as declared in the eventTypes object.
Defines the appearance of types of events.
string
default: 'default' The name of the event type that this type inherits any unspecified properties from.
string | 'from' | 'to' | 'entity' | 'inverse'
default: 'entity' The color of events of this type, either a single color or one of these values. Also applies to events with more than 2 entities.
- 'from' - Event takes its color from its first 'from' entity.
- 'to' - Event takes its color from its first 'to' entity.
- 'entity' - Event has a color gradient matching the color of each entity it joins with.
- 'inverse' - Event has a color gradient with each end matching the opposite entity's color. For events with more than 2 entities, the color gradient follows the 'from' coloring behavior.
number | string
default: 1.5 The width of the event line for events of this type.
- If a number, is used directly as the line width in px units.
- If a string, the value of the corresponding property on the event's
dataobject is used instead, and an adjustment is applied to these values to even the distribution of the line widths throughout the dataset.
boolean
default: true Controls if arrows should be shown on events of this type.
An object specifying the entities whose rows are expanded (according to the expandedRows options), space permitting, and the expansion mode being used.
An object containing an image data URL.
url
required string The URL containing the blob url for the exported image.
Defines the attributes of a font icon.
string The color of the font icon. Default is the timeline's background color.
number
default: 0 The horizontal offset as a percentage of the font icon's size.
number
default: 0 The vertical offset as a percentage of the font icon's size.
string The name of the icon font family.
number | string
default: 'normal' The weight of the font.
number
default: 1 The scale factor of the font icon.
string The text of the font icon. Can be an escaped character code or the icon character itself.
Defines the attributes of a glyph.
Defines a color to be used for heatmap cells with a value greater than or equal to the step value.
Defines a color to be used for a heatmap cell that includes an event of the specified type.
Defines the attributes of a label.
string | 'event'
default: 'event' The color of the label background.
string
default: '#242c32' The color of the label text.
string | 'event'
default: 'event' The color of the label hint.
'up' | 'down' | 'horizontal'
default: 'horizontal' The orientation of the label.
'roundrect' | 'rectangle'
default: 'roundrect' The shape of the label.
string | LabelFontIcon The text to display in the label.
Defines the attributes of a font icon for an Event Label.
string The name of the icon font family.
number | string
default: 900 The weight of the font.
text
required string The text of the font icon. Can be an escaped character code or the icon character itself.
An object containing the mode of calculation for the width of the label area and the width. See Entity Label Area Width.
Defines a marker drawn across the timeline at a specified time.
string The color of the marker circle and line.
label
required string The text for the label of the marker.
string The color of the marker label.
boolean Whether to show the marker label and circle at the bottom of the timeline.
boolean Whether to show the marker label and circle at the top of the timeline.
boolean Whether to show the vertical marker line. A marker can only be displayed if either showAtTop or showAtBottom is set to 'true'. If both are set to 'false', showLine has no effect and the line is not drawn.
The time that the marker is located at, either a Date in local time, a millisecond number in UTC, or a TimeRange object.
number The number of nanoseconds to add to the time value.
An object describing the targeted sub-item.
number The index of the sub-item.
subId
required string Encoded information unique to the sub-item.
Date The time property of the sub-item.
number The number of nanoseconds to add to the time value.
number The value property of the sub-item.
x
required number The distance from the left edge of the Timeline element to the center of the sub-item.
y
required number The distance from the top edge of the Timeline element to the center of the sub-item.
number The width of the sub-item in pixels.
number The height of the sub-item in pixels.
Defines the data to load into the timeline.
entities
required object A dictionary of entities to be displayed in the timeline, where the keys are the entity ids and the values are Entity objects. Ids must be unique across both entities and events.
object A dictionary of entity types, where the keys are the entity type names and the values are EntityType objects. May specify properties for the built-in 'default' entity type.
events
required object A dictionary of events to be displayed in the timeline, where the keys are the event ids and the values are Event objects. Ids must be unique across both entities and events.
object A dictionary of event types, where the keys are the event type names and the values are EventType objects. May specify properties for the built-in default event type.
'firstevent' | 'lastevent' | 'keyorder' | 'alphabetical' | 'shorteneventlines'
default: 'shorteneventlines' The ordering of entity groups, and entities within a group:
- 'alphabetical' - Order alphabetically by the first letter of the entity labels.
- 'firstevent' - Order by the time of the first event associated with the entity.
- 'lastevent' - Order by the time of the last event of each entity (ascending).
- 'keyorder' - Order by the indices of the entities data object.
- 'shorteneventlines' - Order to shorten the vertical event lines between entities.
object A dictionary of time series charts, where the keys are the time series chart ids and the values are TimeSeriesChart objects. Ids must be unique.
object A dictionary of time series charts stacks, where the keys are the time series chart stack ids and the values are TimeSeriesChartStack objects. Ids must be unique.
A range of time.
end
required Date | number The end of the time range as a Date in local time, or a millisecond number in UTC.
number The number of nanoseconds to add to the end time value.
start
required Date | number The start of the time range as a Date in local time, or a millisecond number in UTC.
number The number of nanoseconds to add to the start time value.
Defines a time series chart.
string The color of the line connecting data points in the time series chart. An alpha value is applied to the area under the chart.
data
requiredThe time series data.
number
default: 0.3 The alpha value applied to the area under the time series chart line. Set to 0 to remove the shaded area.
string The label for the time series chart. The label is not shown if the chart is in a stack.
string The label color.
'solid' | 'dashed'
default: 'solid' The style of line connecting data points in the time series chart.
'linear' | 'step'
default: 'linear' The type of line connecting data points in the time series chart.
A data point in a time series chart.
Defines a time series chart stack.
chartIds
required string[] The ids of the time series charts included in the stack.
string The label for the stack.
string The stack label's color.
annotations
required { [id: string]: Annotation } entities
required { [id: string]: Entity } entitySelection
required string[] entitySelectionEnabled
required boolean entityTypes
required EntityTypes | undefined events
required { [id: string]: Event } eventSelection
required string[] eventSelectionMode
required boolean eventTypes
required EventTypes | undefined expandedRows
requiredfocus
required string[] highlight
required string[] labelAreaWidth
requiredlens
required string | null options
requiredordering
required OrderingName overrideStyles
required ({ ids: string | string[]; style: EntityStyle | EventStyle })[] pin
required string[] reveal
required string[] timeSeriesCharts
required { [id: string]: TimeSeriesChart } | undefined timeSeriesChartStacks
required { [id: string]: TimeSeriesChartStack } | undefined