Manifest
The manifest is the machine-validated contract between a plugin and Oruva.
plugin.json uses manifest schema 2. The required keys are schema_version, id, name, version, entry, permissions, capabilities, and actions; every other key is optional and no other keys are allowed (additionalProperties: false). The capabilities object must be present even when a plugin needs nothing beyond the selected asset — each of its four blocks is required and may simply be empty.
Schema-1 manifests still load: Oruva validates the original declaration, then runs the plugin under a fixed least-privilege schema-2 view (asset.read + filesystem.write; filesystem read selected_asset, write plugin_temp; no network destinations, no process targets, no browser origins). A schema-1 plugin that needs the network, the library root, or the browser therefore cannot get it until it moves to schema 2. New plugins must ship schema 2.
Field-by-field
| Field | Required | Constraints |
|---|---|---|
schema_version | yes | Must be 2 for new plugins. 1 is accepted for existing plugins and migrated to the fixed least-privilege view described above. |
id | yes | Lowercase letters, digits, ., _, -; starts with a letter or digit; max 64 chars; matches the folder name case-insensitively. |
name | yes | User-facing name, max 128 chars. |
version | yes | Strict semantic version (1.2.3, prereleases like 1.2.3-beta.1 allowed; no leading zeros), max 64 chars. |
description | no | 1–500 chars. Shown in the Plugin Center. |
author | no | Object: name (required, max 128) and optional url (http/https, max 2048). |
homepage | no | http/https URL, max 2048 chars. |
license | no | Free text, 1–128 chars (for example, MIT). |
icon | no | Relative path inside the folder; PNG, JPEG, WebP, or SVG, max 512 KiB. Shown on Discover cards (bundled and store listings included), on Installed rows and linked development rows in the Plugin Center, in the right-click Plugins submenu, and in the UI-action modal title bar. Oruva renders it as a single-colour silhouette in the theme's ink, gold, or white — so draw solid shapes on a transparent background and never bake in a tile or plate; an opaque background becomes a solid square. Square, 96×96 or larger recommended. Not part of the approval hash on its own — but changing the file's bytes changes the content hash, which is. |
runtime | no | "executable" (default) or "python". Python entries run on Oruva's bundled Python — never assume a system Python or file association exists. |
entry | yes | Relative path to the program that runs, max 1024 chars. Must exist and be a regular file. |
compatibility | no | min_app_version / max_app_version (semver) and platforms (any of windows, macos, linux; defaults to ["windows"]). Portable plugins must list every supported platform explicitly, for example ["windows", "macos"]; omission is not platform-agnostic. An incompatible plugin stays visible but cannot be enabled or executed. |
permissions | yes | Array from the list under Permissions. Unknown or duplicate entries are errors. The array may be empty. |
capabilities | yes | The structured object described next. It must agree exactly with permissions. |
actions | yes | Array of action objects described below. The validator imposes no item-count minimum or maximum. |
Actions
Each action is an object with these fields and no others:
| Field | Required | Constraints |
|---|---|---|
id | yes | Same character rules as the plugin id; unique within the plugin. |
label | yes | Menu text the user sees, 1–128 chars. |
accepts | yes | Non-empty, duplicate-free array of media types this action applies to: image, video, audio, font, 3d, design, archive, document, file. The action only appears for matching assets. |
args | yes | Argument array; each string is at most 4096 chars. Oruva launches with an argument vector, never a shell string — there is no shell quoting, expansion, or shell-injection surface. The validator imposes no item-count limit. |
icon | no | Relative path inside the plugin folder with the same rules as the plugin icon (PNG, JPEG, WebP, or SVG, max 512 KiB). Shown for that action's row in the right-click Plugins submenu; an action without one inherits the plugin icon. Served at /api/plugins/<id>/actions/<action-id>/icon. The path is not part of the approval hash; the file's bytes count toward the content hash like every other file. |
ui | no | Relative path inside the plugin folder, max 1024 chars, normally ui.html. When present and readable, the action opens a modal UI instead of immediately taking the headless path. |
Placeholders
Inside manifest args, these placeholders are substituted for a headless run:
| Placeholder | Meaning | Requires permission |
|---|---|---|
{asset.path} | Resolved local path of the asset file | asset.read |
{asset.name} | Asset filename | asset.read |
{asset.id} | Numeric Oruva asset id | asset.read |
{library.path} | Active library folder | library.read |
Any other {...} token is a validation error, and using a placeholder without declaring its permission is a validation error too. The asset path always comes from Oruva's database by id — a caller cannot substitute an arbitrary path.