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.
Strict parsing
Section titled “Strict parsing”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.
A complete example
Section titled “A complete example”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.
Top-level fields
Section titled “Top-level fields”| 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”.
permissions
Section titled “permissions”| 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.
backend
Section titled “backend”| 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. |
update
Section titled “update”| 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
Section titled “settings”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:
keyis required, unique, and matches[a-z0-9][a-z0-9._-]*.labelis required.typeis one oftext,secret,number,boolean,select,url,camera,group.- A
selecthas at least one option, and every option has avalue. - A
grouphas at least one field. Its fields follow the same rules, may not begrouporsecret, and their keys are unique within the group.
Validation
Section titled “Validation”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.
What Aperture stores
Section titled “What Aperture stores”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.