What is a dashboard definition?

A dashboard definition is a JSON schema containing five core sections, a description, and a title. Each of the five core sections contributes to creating a dashboard.

Section	Description
visualizations	Customize visualization options, such as visualization colors and labels.
dataSources	Specify your data sources, searches, and options for each created search.
defaults	Set global defaults that apply to all specified visualizations, such as the same color scheme for all pie charts.
inputs	Define input types and options, such as a multiselect dropdown.
layout	List inputs, change the canvas size, and modify dashboards.

The following is a code example of the five core sections as empty objects and the description and title as empty strings.

{
  "visualizations": {},
  "dataSources": {},
  "defaults": {},
  "inputs": {},
  "layout": {},
  "description": "",
  "title": ""
}

The source editor provides limited validation, and you can't select the editor's Back button to save your changes if you have formatting errors. You might want to use a JSON validator to ensure that your formatting is correct.

How to format JSON stanzas

Each of the five core sections is defined as a JSON-formatted stanza. Data sources, visualizations, inputs, defaults, and layout have similar hierarchies but crucial differences.

For example, naming a data source is different from naming a visualization. You can give your data source stanza a name, separate from the unique ID, using the name property. For visualizations, you can use the title property to provide a visualization with a title.

Using stanza punctuation

The following are a few standard JSON formatting rules with accompanying code examples.

When setting options in the options property, Boolean values and numbers do not require quotes.

"options": {
  "majorFontSize": 36,
  "deltaFontSize": 16,
  "deltaColor": "> deltaValue | rangeValue(deltaColorEditorConfig)",
  "showSparklineAreaGraph": true,
  "backgroundColor": "transparent"
}

Strings, such as plain text and hexadecimal color codes, must be wrapped in quotes.

"options": {
  "markdown": "# Overall Equipment Effectiveness (OEE) Metrics",
  "fontColor": "#999A9C"
}

Arrays must be enclosed in brackets.

"options": {
  "orientation": "horizontal",
  "backgroundColor": "transparent",
  "gaugeRanges": [
    {
      "from": 75,
      "value": "#EC4B43",
      "to": 100
    },
    {
      "from": 50,
      "value": "#FAE75F",
      "to": 75
    },
    {
      "from": 0,
      "value": "#61CAFA",
      "to": 50
    }
  ]
},

The list of options you use must be enclosed in curly braces, and commas must come at the end of the line after each option entry except the last.

"options": {
  "fillColor": "#080D12",
  "strokeColor": "transparent",
  "fillOpacity": 0.9
}

Commas must separate each stanza in a section except for the last. For example, suppose there are three visualization stanzas in the visualization section of a dashboard definition. In that case, each stanza is separated by a comma after the final closing curly brace, with the exception of the last visualization.

"visualizations": {
  "viz_qoHJXrYE": {
    "type": "splunk.markdown",
    "options": {
      "markdown": "# Business Operations Metrics",
      "fontColor": "#999A9C"
    }
  },
  "viz_9evXJmvv": {
    "type": "splunk.rectangle",
    "options": {
      "fillColor": "#080D12",
      "strokeColor": "transparent",
      "fillOpacity": 0.9
    }
  },
  "viz_RIFCcAe3": {
    "type": "splunk.markdown",
    "options": {
      "markdown": "# Body Assembly",
      "fontColor": "#7AD3F0"
    }
  }
}

Commas must separate each property setting except the last.

{
  "visualizations": {},
  "dataSources": {},
  "defaults": {},
  "inputs": {},
  "layout": {},
  "description": "",
  "title": ""
}

If you get formatting error messages, you can use one of the many JSON formatting websites to check your code to identify the error.

Example of a dashboard definition

View and edit your dashboard definition in the source editor. The dashboard definition is the JSON source code that renders the dashboard in the visual editor. The following dashboard definition is a complete example. An overview of each section follows the example.

Source code

Expand the box to view the complete definition. You can copy and paste the code into your own instance to see the data at work.

{
    "title": "Firewall Pie Chart",
    "description": "Firewall hosts by percentage",
    "inputs": {
        "input_global_trp": {
            "options": {
                "defaultValue": "-24h@h,now",
                "token": "global_time"
            },
            "title": "Global Time Range",
            "type": "input.timerange"
        }
    },
    "defaults": {
        "dataSources": {
            "ds.search": {
                "options": {
                    "queryParameters": {
                        "earliest": "$global_time.earliest$",
                        "latest": "$global_time.latest$"
                    }
                }
            }
        }
    },
    "visualizations": {
        "viz_BHTFSi0R": {
            "dataSources": {
                "primary": "ds_sKOnz7iP"
            },
            "options": {
                "labelDisplay": "valuesAndPercentage"
            },
            "type": "splunk.pie"
        }
    },
    "dataSources": {
        "ds_sKOnz7iP": {
            "name": "Search_1",
            "options": {
                "query": "| inputlookup firewall_example.csv\n| stats count by host"
            },
            "type": "ds.search"
        }
    },
    "layout": {
        "globalInputs": [
            "input_global_trp"
        ],
        "layoutDefinitions": {
            "layout_1": {
                "options": {
                    "display": "auto-scale"
                },
                "structure": [
                    {
                        "item": "viz_BHTFSi0R",
                        "position": {
                            "h": 470,
                            "w": 800,
                            "x": 140,
                            "y": 60
                        },
                        "type": "block"
                    }
                ],
                "type": "absolute"
            }
        },
        "tabs": {
            "items": [
                {
                    "label": "New tab",
                    "layoutId": "layout_1"
                }
            ]
        }
    }
}

The visualizations section

At the root of the JSON visualization section is "visualizations": { after which, all of your visualization stanzas are listed. Each visualization has a type. For example, a pie chart is of type splunk.pie.

Visualization options

Each visualization has an options field. All options available for that particular visualization are listed with each visualization topic and in the Configuration options reference. For more information on options available for each visualization, see the Configuration options reference.

All visualizations are called in the layout section.

The following is a code example of the visualizations section with a visualization stanza for a pie chart.

"visualizations": {
  "viz_BHTFSi0R": {
    "type": "splunk.pie",
    "options": {
      "labelDisplay": "valuesAndPercentage"
    },
    "dataSources": {
      "primary": "ds_sKOnz7iP"
    }
  }
},

Visualization fields and settings

Each visualization can have the following fields:

Field	Description	Required?
The unique ID	The unique ID is automatically generated, but can be changed. If you change it, however, you must also change the visualization's ID in the layout section.	Yes
type	The type is the kind of visualization you are using. For example, the table visualization type is splunk.table. You can change the type in the source code, much like using the Visualization Picker in the visual editor. Ensure your search results contain the fields needed for your visualization type. For example, visualization maps need latitude and longitude fields. Without them, the map will not render.	Yes
title	This is the title name that will display on your visualization. It is not the same as the unique ID and will not change the unique ID.	No
description	You can use this field to add more context to your visualization within the visualization panel.	No
options	In this field, apply options to your visualizations, such as series colors, axis visibility, and background color.	No
containerOptions	In this field, specify the color of your visualization's title and description. The following is a source code example of containerOptions: "containerOptions": { "title": { "color": "#fcba03" }, "description": { "color": "#b103fc" } },	No
hideWhenNoData	Set the hideWhenNoData option to true to conceal the visualization if no data is available to populate the visualization results.	No
context	This is the field where dynamic variable elements are defined. For example, if you've formatted a table column to change colors according to a range of values, the numeric ranges and values are specified in the context section.	Yes, if dynamic elements are used, and only with visualizations of type, splunk.<visualization>.
dataSources.primary	This is where the unique ID of your primary data source is listed. A visualization can have only one primary data source.	No
dataSources.annotation	This is where the unique ID of your annotation data source is listed. annotation is the only secondary data source that has its own designated name.	No

The dataSources section

The dataSources section of the dashboard definition is where you can modify the data source stanzas created in the source editor. You can add searches to your visualizations in the data source section of the Configuration panel or directly in the dataSources section of the dashboard definition. At the root of the section is "dataSources": {. This is where you place each data source stanza.

Unique IDs

When you create a new data source in the form of an ad hoc search or chain search through the visual editor Configuration panel, a unique ID is automatically created for each data source. Each data source must have a unique ID. You can change this unique ID as long as it remains unique in your dashboard definition.

Data source types

Each data source has a type field. There are four data source types:

• ds.search
• ds.chain
• ds.savedSearch
• ds.test

Data source options

Each data source has an options field. For more information on data sources and their types, see Data source options and properties.

The following code example uses "type": "ds.search" because the data source is using a search to gather data.

"dataSources": {
  "ds_sKOnz7iP": {
    "type": "ds.search",
    "options": {
      "query": "| inputlookup firewall_example.csv\n| stats count by host"
    },
    "name": "Search_1"
  }
},

The defaults section

Use the defaults section to define global settings for any or all data source or visualization types. All settings applied at the component or stanza level override those in the defaults section. For more details about the defaults section, and examples, see Set global and local defaults.

The following is an example of what a defaults section looks like:

"defaults": {
  "dataSources": {
    "ds.search": {
      "options": {
        "queryParameters": {
          "latest": "$global_time.latest$",
          "earliest": "$global_time.earliest$"
        }
      }
    }
  }
},

The inputs section

Inputs have fields for their unique ID, type, title, and options. Like visualizations, inputs must be called in the layout section.

The following example is an input of the time range type:

"inputs": {
  "input_global_trp": {
    "type": "input.timerange",
    "options": {
      "token": "global_time",
      "defaultValue": "-24h@h,now"
    },
    "title": "Global Time Range"
  }
},

To view the available input types, their associated options, and more examples, see Use inputs to make dashboards dynamic.

The layout section

The layout stanza has four main settings fields:

Settings field	Description
options	The options field is where you set your dashboard level settings.
layoutDefinitions	The layout definition field is where you set your tab level settings within a dashboard.
globalInputs	For inputs that appear above the canvas, the glablInputs field is where you list any inputs in your dashboard by their ID. For inputs that appear in the canvas, you list the input IDs in the structure field of the layout section.
structure	The structure field is where you define the width and height of visualizations and inputs. It is also where visualizations are placed on the x-axis and y-axis of the dashboard canvas. If a visualization's ID is not in the structure field, it doesn't appear on the dashboard canvas.
type	The type field is where you set the dashboard to either an absolute or grid layout. Don't change this setting for populated dashboards, especially from absolute to grid, because it will likely result in losing your visualizations and an error message.

The following is an example of a layout stanza:

"layout": {
 "options": {
   "submitButton": true,
   "showTitleAndDescription": true,
   "submitOnDashboardLoad": false,
 },
 "globalInputs": [
   "input_eriPsPT8"
 ],
 "tabs": {
   "items": [
     {
       "layoutId": "layout_1",
       "label": "Layout 1",
       "icon": "icon_id"
     }
   ],
   "options": {
     "barPosition": "top",
     "showTabBar": false
   }
 },
 "layoutDefinitions": {
   "layout_1": {
     "type": "grid",
     "options": {
       "backgroundColor": "aquamarine",
       "display": "auto",
       "gutterSize": 8,
       "width": 1200,
       "height": 900
     },
     "structure": [
       {
         "item": "viz_1",
         "type": "block",
         "position": {
           "x": 0,
           "y": 0,
           "w": 600,
           "h": 316
         }
       },
       {
         "item": "viz_2",
         "type": "block",
         "position": {
           "x": 600,
           "y": 0,
           "w": 600,
           "h": 316
         }
       }
     ]
   },
   "layout_2": {
     "type": "absolute",
     "options": {
       "backgroundColor": "blue",
       "display": "actual-size",
       "gutterSize": 2,
       "width": 1200,
       "height": 900
     },
     "structure": [
       {
         "item": "viz_1",
         "type": "block",
         "position": {
           "x": 0,
           "y": 0,
           "w": 600,
           "h": 316
         }
       }
     ]
   }
 }
}

The layout is also where you modify the canvas of your dashboard. For more information, see Compare absolute and grid layouts and Layout configuration options.

Default options for the visualizations and layout sections

When some defaults are not changed in the visual editor, the corresponding source options and properties might not appear in the source editor. For example, if you don't change the default width and height of the dashboard, the width and height options and their settings don't appear in the editor. Similarly, if you don't change the display default, this option and setting also don't appear in the source code. To have them appear, you can either change the defaults or add and edit them manually in the source editor. The following is a layout example of these settings after the defaults have been changed in the visual editor.

"layout": {
  "tabs": {},
  "layoutDefinitions": {
    "type": "absolute",
    "options": {
        "backgroundColor": "#C093F9",
        "backgroundImage":
          { "x": 0,                        
            "y": 0,                       
            "src": "splunk-enterprise-kvstore://5f6cc9810b19516995423ad1",                        
            "sizeType": "contain"            
          },
        "submitButton": true,
        "width": 1198,
        "height": 898,
        "display": "auto-scale"
    },
    "structure": []
  },
  "globalInputs": [],
}