Manifest

Every pane has a manifest.json. It says how big the pane is, which settings it has, which secrets it needs and which hosts it may call. It is a JSON object of at most 16 KB. Unknown fields are refused at every level, so a typo in a field name is reported rather than ignored.

Full example

A pane that lists open pull requests. It uses every kind of field.

{
  "name": "Open pull requests",
  "description": "Open pull requests for a few repositories, newest first.",
  "size": { "default": [4, 6], "min": [3, 4], "max": [8, 12] },
  "props": {
    "title": { "type": "string", "label": "Title", "default": "Pull requests" },
    "repos": { "type": "string[]", "label": "Repositories", "default": ["owner/repo"] },
    "count": { "type": "number", "label": "How many", "default": 20, "min": 1, "max": 100 },
    "showDrafts": { "type": "boolean", "label": "Show drafts", "default": false },
    "sort": { "type": "select", "label": "Sort", "options": ["newest", "oldest"], "default": "newest" }
  },
  "secrets": {
    "GITHUB_TOKEN": { "label": "GitHub token", "hosts": ["api.github.com"], "required": true }
  },
  "network": ["api.github.com"]
}

Fields

Field	Type	Default	Rule
name	string	(required)	1 to 80 characters, not counting spaces at either end.
description	string	none	Up to 500 characters.
size	object	(required)	The pane’s size in grid cells. See size.
props	object	{}	Up to 30 settings. See props.
secrets	object	{}	Up to 10 secret slots. See secrets.
network	string[]	[]	Up to 20 hosts that dash.fetch may call. See network.

name and description are notes for you. The canvas and My panes show the pane’s own name, which you set when you create or rename the pane.

size

Sizes are [width, height] in grid cells. Each number is a whole number of at least 1.

Field	Type	Default	Rule
default	[number, number]	(required)	The size a pane gets when you add it to a canvas.
min	[number, number]	[1, 1]	The smallest size it can be resized to.
max	[number, number]	[24, 40]	The largest size. Width at most 24, height at most 40.

min must be no larger than default, and default no larger than max, in both width and height. A pane also cannot be wider than its canvas, which has 12 columns unless you change it.

If a new version changes min or max, panes already on a canvas keep their current size; the new limits apply when you resize them.

props

Props are a pane’s settings. Each one appears as a field in the pane’s settings on the canvas, and in the preview’s props form. The code reads them from dash.props.

The key is the prop’s name: a letter, then letters, digits or _, up to 64 characters in all. Every prop has a type and a label. The label is what the form shows, 1 to 80 characters.

type	Other fields	The value in dash.props
string	default: a string of up to 1,000 characters.	A string of up to 1,000 characters.
number	default, min, max: numbers, all optional. min must not be above max, and default must be between them.	A number between min and max.
boolean	default: true or false.	true or false.
select	options: 1 to 50 different strings, each 1 to 80 characters (required). default: one of them.	One of the options.
string[]	default: up to 50 strings, each up to 1,000 characters.	A list of up to 50 strings.

Which value a pane gets, for each prop the manifest declares:

1. The value set on the canvas, if it is still valid for the prop as it is now defined.
2. Otherwise the default.
3. Otherwise nothing: the prop is missing from dash.props.

So if a new version changes a prop’s type or narrows its range, a value that no longer fits falls back to the default. A value for a prop the manifest no longer declares is ignored. dash.onProps tells the code when a value changes.

secrets

Secret slots are the secrets a pane needs. The key is the slot’s name: a capital letter, then capital letters, digits or _, up to 64 characters in all. The code uses it in a placeholder, {{secrets.GITHUB_TOKEN}}.

Field	Type	Default	Rule
label	string	(required)	What the binding form shows. 1 to 80 characters.
hosts	string[]	(required)	1 to 10 hosts this slot may be sent to, no duplicates. Each must also be in network, written the same way.
required	boolean	false	When true, a placed pane does not start until the slot is bound.

The hosts entries follow the same rules as network, wildcards included. The secret bound to the slot has its own list of allowed hosts, and a call must match both. How binding and placeholders work is in Secrets.

network

The hosts dash.fetch may call. A call to any other host is refused with PROXY_HOST_NOT_ALLOWED. With no network, the pane can make no calls.

Each entry is a hostname:

• lower case, made of letters, digits, - and ., at most 253 characters;
• at least two labels, such as api.example.com, each label at most 63 characters and not starting or ending with -;
• no scheme, port or path: api.example.com, not https://api.example.com:443/v1;
• not an IP address, and the last label is not a number;
• not a name ending in .internal, .local, .localhost, .test, .example or .invalid;
• international names in their punycode form (xn--…).

A wildcard is allowed as one leading *. label. *.example.com matches api.example.com, but not example.com or a.b.example.com. A wildcard must not cover a whole public suffix: *.com, *.co.uk and *.github.io are refused.

A listed host is not enough on its own. When the call is made, the host must also resolve to a public address, or the call is refused with PROXY_BLOCKED_ADDRESS.

When it is checked

• Save version checks the whole manifest. If anything is wrong, the problems are listed with where they are, such as “manifest.json · size.min must be ≤ size.default”, and no version is saved.
• The draft is saved as you type, even when it is not valid. While the draft’s manifest is not valid, the preview’s calls to dash.fetch are refused with VALIDATION_FAILED, and preview secrets cannot be bound.
• A canvas runs the latest saved version, so its manifest is always one that passed these checks.

The file must be plain JSON: no comments and no trailing commas.