What is a dashboard definition?

A dashboard definition is a JSON schema with core sections that contribute to creating a dashboard, including inputs, defaults, visualizations, data sources, layout, and expressions.

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

Section Description
inputs Define input types and options, such as a multiselect dropdown.
defaults Set global defaults that apply to all specified visualizations, data sources, and tokens. For example, you can set a global default so that all pie charts use the same color scheme. See Set defaults.
visualizations Customize visualization options, such as visualization colors and labels.
dataSources Specify your data sources, searches, and options for each created search.
layout List inputs, change the canvas size, and modify dashboards.
expressions Specify expressions for conditional panel visibility or token evaluation.
applicationProperties Specify dashboard-level settings, such as view options.

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

JSON 
{
  "title": "",
  "description": "",
  "inputs": {},
  "defaults": {},
  "visualizations": {},
  "dataSources": {},
  "layout": {},
  "expressions": {},
  "applicationProperties": {}
}
Note: The source editor provides limited validation, and you can't select the editor's Apply 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

JSON stanzas define core sections like data sources and visualizations, each with unique properties. Proper punctuation and formatting are crucial for accurate representation and functionality.

Each core section 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.

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

You must wrap strings, such as plain text and hexadecimal color codes, in quotes.

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

You must enclose arrays in brackets.

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

You must enclose a list of options in curly braces, and commas must come at the end of the line after each option entry except the last.

JSON 
"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 3 visualization stanzas in the visualization section of a dashboard definition. In this case, separate each stanza with a comma after the final closing curly brace with the exception of the last visualization.

JSON 
"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.

JSON 
{
  "visualizations": {},
  "dataSources": {},
  "defaults": {},
  "inputs": {},
  "layout": {},
  "description": "",
  "title": ""
}
Note: If you get formatting error messages, you can use a JSON formatting website to check your code to identify the error.

Example of a dashboard definition

The dashboard definition consists of JSON source code that allows you to view and edit dashboards in the source editor. See a complete example with an overview of each section.

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

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.

JSON 
{
    "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": {
            "containerOptions": {
                "visibility": {
                    "conditions": ["condition_1"]
                }
            },
            "dataSources": {
                "primary": "ds_sKOnz7iP"
            },
            "showLastUpdated": false,
            "showProgressBar": false,
            "type": "splunk.table"
        }
    },
    "dataSources": {
        "ds_sKOnz7iP": {
            "name": "Activity by host",
            "options": {
                "enableSmartSources": true,
                "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"
                }
            ]
        }
    },
    "expressions": {
        "conditions":{
            "condition_1": {
                "name": "Minimal activity",
                "value": "$Activity by host:result.count$ <= 500"
            }
        }
    }
}

Inputs section

Inputs require a unique ID, type, title, and options, and must be called in the layout section. Examples include time range inputs with customizable options.

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 a time range input:

JSON 
"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 Inputs.

Defaults section

Define global settings for data sources or visualization types in the defaults section. Element-level settings override defaults.

Use the defaults section to define global settings for any or all data source or visualization types. All settings applied at the element or stanza level override those in the defaults section. For 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:

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

Visualizations section

Define and configure dashboard visualizations, including types, options, fields, and data sources, to control how search results render in Splunk.

The visualizations section of the dashboard definition is where you define all visualizations with a type and various options. 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 information on options available for each visualization, see Visualization configuration options.

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.

JSON 
"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?
Unique ID The unique ID is automatically generated but can be changed. If you change it, however, you must also change the visualization ID in the layout section. Yes
type 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 dropdown in the UI. Ensure your search results contain the fields needed for your visualization type. For example, a map need latitude and longitude fields. Without these fields, the map does not render. Yes
title Title that displays at the top of your visualization panel. It is not the same as the unique ID and does not change the unique ID. No
description Add context to your visualization within the visualization panel. No
options Apply options to your visualizations, such as series colors, axis visibility, and background color. No
containerOptions Specify the color of your visualization title and description. The following is an example of containerOptions:
JSON 
"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 Define dynamic variable elements. 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 using dynamic elements and only with visualizations of type splunk.<visualization>.
dataSources.primary Primary data source unique ID. A visualization can have only 1 primary data source. No
dataSources.annotation Annotation data source unique ID. annotation is the only secondary data source that has its own designated name. No

dataSources section

Learn how to configure and manage dashboard data sources, including unique IDs, data source types, and options for searches and visualizations.

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 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. The following lists possible data source types:

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

Data source options

Each data source has an options field. For 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 uses a search to gather data.

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

layout section

The layout stanza has the following main settings fields:

Settings field Description
options Set dashboard-level settings.
layoutDefinitions Set tab-level settings within a dashboard.
globalInputs For inputs that appear above the canvas, list any inputs in your dashboard by their ID in the globalInputs field. For inputs that appear in the canvas, list the input IDs in the structure field of the layout section.
structure Define the width and height of visualizations and inputs. Place visualizations on the dashboard x-axis and y-axis. If a visualization ID is not in the structure field, it doesn't appear on the dashboard canvas.
type Set the dashboard to 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:

JSON 
"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 your dashboard canvas. See Compare absolute and grid layouts and Layout configuration options.

Expressions section

The expressions section allows modification of conditions for panel visibility and token evaluation logic, including hiding panels based on activity count thresholds.

The expressions section of the dashboard definition is where you can modify conditions for panel visibility and token eval logic.

Code example

The following is a code example of the expressions section for a dashboard with a condition to hide a panel when the activity count is less than 500.
JSON 
{
    "title": "Splunk activity",
    "description": "",
    "inputs": {...},
    "defaults": {...},
    },
    "visualizations": {
        "viz_5KNdO222": {
            "containerOptions": {
                "visibility": {
                    "hideConditions": [
                        "condition_UvMNvMv8"
                    ],
                    "showConditions": [
                        "condition_NEAvRhhN"
                    ]
                }
            },
            "dataSources": {
                "primary": "ds_jnayxJ7I"
            },
            "options": {},
            "type": "splunk.line"
        }
    },
    "dataSources": {
        "ds_jnayxJ7I": {...}
    },
    "layout": {...},
    "expressions": {
        "conditions": {
            "condition_NEAvRhhN": {
                "name": "Activity spike",
                "value": "$activity:result.splunkd$ > 7500"
            },
            "condition_UvMNvMv8": {
                "name": "User selection",
                "value": "$not(\"*\" in [\"user\"])"
            }
        }
    }
}

applicationProperties section

The applicationProperties section allows modification of dashboard-level settings, including visibility options for export and action menus, and optimized rendering for time-series charts.

The applicationProperties section of the dashboard definition is where you can modify dashboard-level settings.

Code example

The following code example of the applicationProperties section is for a dashboard with the Hide export and Hide action menu options activated.
JSON 
"applicationProperties": {
        "hideExport": true,
        "hideViewModeActionMenu": true
    }

applicationProperties fields and settings

The following properties are included in the applicationProperties section. When set to their default values, they do not show in the source code.

Settings field Default value Description
collapseNavigation false Specifies whether the Splunk bar, application bar, and dashboard action menu collapse by default when viewing a dashboard.
downsampleVisualizations true Specifies whether to apply optimized rendering to time-series charts.
hideViewModeActionMenu false Specifies whether the action menu on visualization panels is visible when viewing a dashboard.
hideEdit false Specifies whether the Edit button is visible when viewing a dashboard.
hideOpenInSearch false Specifies whether the Open in Search button is visible when viewing a dashboard. hideViewModeActionMenu supersedes this option.
hideExport false Specifies whether the export actions are visible in the dashboard action menu and visualization panel action menu.

Default options for the visualizations and layout sections

If you do not change default values in the UI, 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 change the default values or add and edit them manually in the source editor. The following is a layout example of these settings after changing the default values in the UI.

JSON 
"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": [],
}