Panel descriptor: panel.json

Stability: provisional · Panel API version: 1.0 · SDK path: sdk/1/

A panel is a directory holding panel.json, an HTML entry page, and optionally panel.sample.json and panel.py. panel.json declares what the panel is; the host validates it when panels are discovered and skips a panel whose descriptor is invalid, reporting why.

Keys

Key Type Required Default Rule
id string yes — Lowercase dotted segments, each starting with a letter ([a-z][a-z0-9_]*). Must equal the panel directory's name. Ids starting with core. are reserved for panels shipped with SciStudio.
api_version string yes — MAJOR.MINOR with no leading zeros. The major must be the one this host serves (1); the panel loads the SDK from sdk/1/.
contexts array of string yes — Non-empty list of distinct values from preview, interactive, miniapp.
types array of string no [] Distinct registered type names; Collection[<Type>] claims a collection of that type. Required (non-empty) when contexts includes preview; exactly one type when it includes miniapp. The names DataObject, Collection, PlotArtifact are reserved for built-in panels.
priority integer no 0 Orders panels that claim the same type at the same tier; the higher value is chosen. Booleans are refused.
name string no the id Human-readable name for the panel.
description string no "" Human-readable description of what the panel shows.
version string no "" The panel's own version label; not interpreted by the host.
entry string no index.html Path of the page to load, relative to the panel directory. Must stay inside the directory and name an .html file.

Directory rules

  • panel.json must be a JSON object no larger than 64 KiB.
  • Unknown keys are ignored and reported as a validation note.
  • A panel.py beside panel.json is started only for the miniapp context; in any other context it is reported as a note and never run.
  • Discovering a panel never imports or executes its Python.

Contexts

  • preview — shows a data object in the preview area.
  • interactive — the window an interactive block opens to collect a decision.
  • miniapp — a standalone app over one type, optionally backed by panel.py.

What each context may call is in the panel SDK reference.

panel.sample.json

panel.sample.json sits beside the panel page and stands in for the host when the page is opened directly. The SDK gives the sample context the operations and services of a real context of that kind, with call and submitAnswers always present for miniapp; without a host, open and save reject with unsupported.

Key Type Description
context "preview" \| "interactive" \| "miniapp" Required. The context to simulate.
input (optional) object Becomes scistudio.input; give ref for preview and miniapp. Defaults to {}.
viewState (optional) any Becomes scistudio.viewState.
theme (optional) object Becomes scistudio.theme. Defaults to {mode: "light", tokens: {}}.
reads (optional) object Answers for read, keyed by JSON.stringify({ref, op, params}) or by the operation name.
calls (optional) object Answers for call, keyed by JSON.stringify({fn, args}) or by the function name.