Skip to content

The manifest

Every extension bundle has a manifest.json at its root. It names the extension, declares everything it may do, and says where its code lives. This page lists every field and every check Aperture runs on it. The parser lives in internal/ext/manifest.go.

Aperture decodes the manifest with unknown fields rejected, at every level. A misspelled permission such as "netwrok" fails the install with json: unknown field "netwrok" instead of silently granting nothing. The file must be plain JSON: no comments and no trailing commas.

This is the manifest of the ha-room-lights example, a UI extension that controls a Home Assistant light from the camera view:

{
"manifest": 1,
"id": "com.example.ha-room-lights",
"name": "Home Assistant Room Lights",
"version": "3.2.0",
"author": "Jane Doe",
"description": "Control a camera's room light in Home Assistant from its camera view.",
"minApiVersion": "v1",
"permissions": {
"data": { "cameras": "read" },
"cameras": "all",
"network": ["{{setting:ha_url}}"]
},
"settings": [
{
"key": "ha_url",
"label": "Home Assistant URL",
"type": "url",
"required": true,
"placeholder": "https://192.168.1.10:8123"
},
{
"key": "ha_token",
"label": "Long-lived access token",
"type": "secret",
"required": true
},
{
"key": "lights",
"label": "Camera → light",
"type": "group",
"fields": [
{ "key": "camera", "label": "Camera", "type": "camera", "required": true },
{ "key": "entity", "label": "Light entity", "type": "text", "required": true, "placeholder": "light.hallway" }
]
}
],
"ui": {
"panels": [
{ "slot": "camera-detail", "entry": "ui/panel.html", "title": "Room light" }
]
}
}

The shipped file in examples/ha-room-lights/manifest.json also carries help text and an update block.

Field Type Required Rules
manifest integer yes Must be 1. Any other value, or leaving it out, fails with “unsupported manifest version”.
id string yes Reverse-DNS identifier: two or more dot-separated labels of lowercase letters, digits and inner hyphens, such as com.example.room-lights. No underscores, no capitals. The id is the extension’s permanent identity: it names its folder, its storage and its token, and a bundle with an installed id is treated as an update.
name string yes Shown everywhere the extension appears. Must not be blank.
version string yes major.minor.patch, with an optional pre-release suffix: 1.2.0, 2.0.0-beta.1. Build metadata (+…) is not accepted. Updates compare the three numbers only.
author string no Shown at install and on the row. Empty shows “Unknown author”.
description string no One line, shown at install.
icon string no Path to a PNG inside ui/. See Icon.
minApiVersion string no "" or "v1". Anything else fails: “is newer than this server (v1)”.
permissions object no Everything the extension may do. Absent or empty grants nothing. See permissions.
settings array no The extension’s own settings form. Declaring it implies storage. See Settings and storage.
ui object see below UI panels.
backend object see below The Deno backend.
update object no Where to look for newer versions.

A manifest must declare at least one panel in ui.panels or a backend.entry; otherwise it fails with “an extension must declare at least one of ui.panels or backend.entry”.

Field Type Values
data object A map of domain to level: "read" or "write", and for media also "live". Domains: cameras, events, coverage, segments, media, storage, schedules, zones, detection, site, automation. coverage and segments accept "read" only.
alarm string "arm" only
system string "read" only
cameras "all" or array of strings "all" asks for every camera, including cameras added later. An array of camera ids asks for at most those. Absent means no camera access. Any other string, or an empty id in the array, fails.
network array of strings Each entry is an absolute http or https URL whose host (and port, if given) may be reached, or {{setting:key}} naming a url setting, or {{setting:group.column}} naming a url field inside a group setting.
storage boolean true gives the extension a private key-value store. Implied by settings.

Each data entry is one level, so an extension cannot ask for both "read" and "live" on media. Permissions shows which API scopes each entry becomes and how the consent screen words it.

A network entry keeps only the host and port of the URL: https://hooks.example.com/services/x allows hooks.example.com. A {{setting:…}} entry must be the whole string, for example "{{setting:ha_url}}", and must name a setting declared in the same manifest with type url (or a group with a url column).

Field Type Required Rules
ui.panels array yes, when ui is present One entry per panel. Several panels may use the same slot.
slot string yes camera-detail, dashboard-card, settings, nav-panel, player-toolbar or player-osd. See UI panels.
entry string yes Relative path to the panel’s HTML file, such as ui/panel.html. No leading /, no .., and already in clean form (no ./, no doubled slashes).
title string no The panel’s accessible name, the label of a player-toolbar button and its dropdown, and the page title of a nav-panel. Card slots do not draw it. Falls back to the extension name.
anchor string no player-osd only: top-left, top-right, bottom-left or bottom-right. Default bottom-left. On any other slot it fails with “only valid for the player-osd slot”.

Aperture serves only the ui/ folder to browsers. The manifest check accepts an entry anywhere in the bundle, but a panel outside ui/ returns 404 when it loads, so keep panels under ui/.

A nav-panel makes the extension pinnable to the navigation rail. Pinning stays the administrator’s choice.

Field Type Required Rules
backend.entry string yes, when backend is present Relative path to the TypeScript or JavaScript file Deno runs, such as backend/main.ts. Same path rules as a panel entry.
backend.denoVersion string no The Deno major version you target, such as "2". Recorded for authors; Aperture runs every backend with the Deno it ships (2.9.5) and does not check this value.
Field Type Required Rules
update.url string yes, when update is present URL of a manifest.json for the newest version. Not checked at install; when the update check runs it must be an absolute http or https URL.

Aperture fetches update.url when an administrator opens Settings › Extensions. If that manifest is valid and has a higher major.minor.patch, the row offers an update. Applying it fails with “this bundle is …, not …” if the downloaded bundle has a different id. The bundle it installs is bundle.zip in the same folder as the manifest, so https://example.com/room-lights/manifest.json updates from https://example.com/room-lights/bundle.zip. Each extension therefore needs its own folder on the update server. Applying an update is always an administrator’s click, never automatic; see Update an extension.

icon is a bundle path such as ui/icon.png. It is checked twice:

  • In the manifest: a clean relative path that starts with ui/ and ends in .png.
  • At install: the file must exist, decode as a PNG (not another format renamed), be at most 64 KiB, and measure between 1 × 1 and 256 × 256 pixels.

The icon appears on the extension’s row in Settings › Extensions, as the rail icon when it is pinned, and on its player-toolbar buttons. Aperture always shows it as an image from the extension’s asset route, never as inline markup. Without an icon, Aperture shows the first letter of the name, or a puzzle-piece glyph in the rail.

settings is an array of fields that becomes the form on the extension’s row. Field shape, types, defaults and validation are on Settings and storage. The manifest check enforces:

  • key is required, unique, and matches [a-z0-9][a-z0-9._-]*.
  • label is required.
  • type is one of text, secret, number, boolean, select, url, camera, group.
  • A select has at least one option, and every option has a value.
  • A group has at least one field. Its fields follow the same rules, may not be group or secret, and their keys are unique within the group.

Aperture checks a bundle when it is uploaded, fetched or taken from a store, before the consent screen opens. Every message below is shown in the Add extensions dialog.

Check Message
JSON is valid and has no unknown fields invalid manifest json: …
manifest is 1 unsupported manifest version 0 (this server understands 1)
id is reverse-DNS id "…" must be a reverse-DNS identifier (e.g. com.example.thing)
name is not blank name is required
version is semver version "…" must be semver (e.g. 1.2.0)
minApiVersion is empty or v1 minApiVersion "…" is newer than this server (v1)
A panel or a backend exists an extension must declare at least one of ui.panels or backend.entry
Each slot is known ui.panels[0]: unknown slot "…"
Each entry is a safe relative path ui.panels[0].entry: "…" must be a relative path inside the bundle (no leading / or ..)
anchor is on a player-osd and known ui.panels[0].anchor: only valid for the player-osd slot / unknown anchor "…"
icon path icon "…" must be a .png inside ui/ (e.g. ui/icon.png)
Each data domain exists permissions.data: unknown domain "…"
Each level is grantable for its domain permissions.data.coverage: "write" is not grantable for this domain
alarm and system values permissions.alarm: only "arm" is valid / permissions.system: only "read" is valid
cameras shape permissions.cameras: "…" is not valid (use "all" or a list of camera ids) / permissions.cameras: empty camera id
Settings schema for example settings: duplicate key "…", settings[0] (…): a select field needs options
network entries permissions.network: "…" must be an absolute http(s) URL … / {{setting:…}} must reference a declared url setting

Then come the checks that need the unpacked files:

Check Message
The zip has no entry with .. or a leading / bad bundle: unsafe path in bundle: …
manifest.json is at the root manifest.json is missing from the bundle
The icon file is a real, small PNG icon file … is missing from the bundle / icon: …
An extension that reads camera data asks for cameras this extension reads camera data but does not request cameras — add "cameras": "all" or a list of camera ids under permissions
No remote imports remote imports are not allowed: …

The camera rule applies when the manifest asks for cameras, events, coverage, segments or media under data without a cameras entry.

The import check reads every .ts, .js, .mjs, .tsx and .jsx file in the bundle, including files under ui/, and rejects from "…" and import("…") specifiers that start with http://, https:// or file:, or are absolute paths. Deno’s --deny-import blocks anything the scan cannot see when the backend runs. See The SDK.

At install and on each update, Aperture stores the manifest in its database together with the permissions it resolved. That stored copy is the one it enforces from then on. Changing manifest.json with Edit files changes the file on disk and nothing else; to change what an extension may do, install a new version.

Extensions · Permissions · UI panels · Settings and storage