Skip to main content

Visualization Language (SedaroVL)

Sedaro Visualization Language (SedaroVL or SVL) is a JSON based format for defining dashboards. A dashboard is an arrangement of visualization widgets with a shared clock.

{
  "name": "Example Dashboard",
  "clock": {
    "start": "2030-01-01T00:00:00.000Z",
    "stop": "2030-01-01T12:00:00.000Z"
  },
  "widgets": [ ... ]
}

Defining Widgets​

A widget is a self-contained visualization component that displays data in a specific format. Each widget is defined by its type, layout properties, and configuration options. All widgets must have a unique id within the dashboard.

SVL supports the following widget types

  • Playback
  • Timeseries
  • Stat
  • Bar
  • Pie
  • Text
  • Table
  • Scatter
  • Data-Grid
  • State-Timeline
  • Sankey
  • Stoplight
  • Video
info

Visit the SVL Playground to explore examples of each widget type and their configuration options.

warning

At least one Playback widget must be defined in order for time dynamic behavior to work correctly.

Creating a Layout​

Widgets are arranged in a grid layout defined by their width and height properties. The grid uses a 12-column auto-flow system, where the width of each widget is specified in terms of the number of columns it spans (1-12). The height is specified in terms of grid rows, with each row having a height of 30 pixels. Widgets are placed left to right, top to bottom, in the order they are defined in the SVL file.

{
  "id": "test_widget",
  "type": "playback",
  "layout": { "width": 12, "height": 8 },
  "options": { ... }
}

While developing a dashboard, you can enable widget dragging by setting "static": false at the root level of the SVL file. This will allow you to rearrange widgets in the rendered dashboard by dragging and dropping them. These changes are not saved to the SVL file and are only for development purposes.

If you would like to view a single widget in isolation, you click the fullscreen button in the widget header to expand it to fill the entire dashboard area.

Providing Data​

Generally, SVL supports two ways to populate data fields: Inline and Artifact Handles.

Inline​

Data can be inlined as part of the SVL file. In this format, data is provided as a list of data frames. Frames are lists where the first value is the timestamp, followed by data values. Timestamps are given as elapsed time in seconds.

// Example inlined dataset
[
  [0, true, false, false],
  [10, false, false, true],
  [20, true, true, true],
  [30, false, true, false]
]

Artifact Handle​

Series data can be fetched from the Artifact Service by providing a reference to the artifact, called an artifact handle. An artifact handle consists of the url to a stream of data, the fields to extract from the stream, and an optional data resolution. Resolution can be used to downsample large data sets and must be a power of two (2, 4, 8, etc). The default value of 1 will fetch the full data set, while the special value 0 will fetch the minimum resolution available.

Replace <your-public-api-host> with the URL of your Sedaro deployment (for instance: https://test.sedaro.us).

{
  "artifact": "https://<your-public-api-host>/api/artifacts/v1/<artifact_id>/streams/<stream_id>",
  "fields": ["component_1.active", "component_2.active", "component_3.active"],
  "resolution": 4
}
note

If the artifact url includes the start, stop, or sampleRate query parameters, these will be replaced using the dashboard clock's start/stop and the handle's resolution.

Datasets​

Most SVL widgets require a dataset to visualize. A dataset can include inlined data or artifact handles.

{
  "dataset": [
    {
      "name": ["Sat 1 Active", "Sat 2 Active", "Sat 3 Active", "Sat 4 Active"],
      "data": [
        [0, true, false, true, false],
        [1, false, true, true, false],
        [2, true, true, false, false],
        [3, false, false, true, true]
      ]
    },
    {
      "name": ["Agent 1 Status", "Agent 2 Status", "Agent 3 Status"],
      "data": {
        "artifact": "https://<your-public-api-host>/api/artifacts/v1/123/streams/456",
        "fields": ["agent_1.status", "agent_2.status", "agent_3.status"]
      }
    }
  ]
}
info

Playback widgets use a slightly different input system for processing data. See the Playback documentation for more information.

Transformations​

Transformations are operations that can be applied to datasets to derive statistical data from a series. The supported transforms are:

  • current: Retrieve the current value of each series based on the dashboard clock.
  • last: Retrieve the latest value of each series.
  • mean: Calculate the average value of each series across the time range.
  • sum: Calculate the total sum of each series across the time range.
  • min: Find the minimum value of each series across the time range.
  • max: Find the maximum value of each series across the time range.

Aggregate​

Some SVL widgets support aggregating data series together by counting occurrences of unique values across series.

For example, this can be used to display a count of how many components have a particular status.

  1. Start with a dataset of every component's status over time
  2. Add the current transform to get the current status of each component
  3. Enable aggregation to count the number of components with each status

Debugging a Dashboard​

All SVL dashboards are validated against the SVL Schema with errors logged to the browser console.

While developing a dashboard, it is recommended to use the SVL Playground to allow for quicker iteration.