version)Plugin versions follow Semantic Versioning: MAJOR.MINOR.PATCH.
| Change type | Increment | Example |
|---|---|---|
| Breaking change (new required capability, command rename) | MAJOR | 1.0.0 → 2.0.0 |
| New feature (new optional capability, new tool) | MINOR | 1.0.0 → 1.1.0 |
| Bug fix, text change, optimization | PATCH | 1.0.0 → 1.0.1 |
schemaVersion)The schemaVersion field describes the plugin.json format version,
not the plugin's own version.
schemaVersion | Status |
|---|---|
1 | ✅ Current standard manifest schema |
2 | ✅ Supported extended schema (adds declarative inboundWebhooks and eventConsumers) |
Chattree will refuse to install a plugin with an unknown schemaVersion.
runtimeApiVersion)The runtimeApiVersion declares which version of the ChattreeHostApi your
plugin was built against.
runtimeApiVersion | Status | Notes |
|---|---|---|
"1.0.0" | ✅ Current stable | Use this for all plugins today |
A new runtimeApiVersion is declared when:
payment.*).Minor additions (new optional operations within existing namespaces) do NOT require a version bump — they are backward compatible.
| Chattree version | Supported schemaVersion | Supported runtimeApiVersion |
|---|---|---|
| 1.0.x | 1, 2 | 1.0.0 |
| Future | 1 (minimum) | 1.0.0+ |
minAppVersionIf your plugin uses features only available from a specific Chattree version,
set minAppVersion in plugin.json:
"minAppVersion": "1.1.0"
Chattree will refuse to install the plugin if the app version is lower.
The package manager evaluates
minAppVersionduring compatibility checks. Provide a valid semantic version when your plugin depends on a minimum app release; verify target app behavior before publishing.
If Chattree removes a capability in a future version:
unknown capability error.success == false).Capabilities will never be silently replaced — the old name will return errors and a migration path will be documented.
If an operation's input/output changes in a backward-incompatible way:
runtimeApiVersion is declared.version in plugin.json following semver.plugin.wasm if the WASM source changed.wasmSha256 and update plugin.json.changelog with release notes..chattree-plugin archive.Users can import the new .chattree-plugin manually. Marketplace updates depend on the deployed catalog and app update flow; test the actual release path before promising automatic updates.
Plugin updates can be distributed through two channels:
409 VERSION_NOT_NEWER if the submitted version is lower than or equal to an existing version) and rejects duplicate (plugin id, version) pairs (409 VERSION_ALREADY_EXISTS). Verify in-app update discovery in the target app release..chattree-plugin): Share the updated .chattree-plugin archive directly; users import it via Settings → Plugins → Importar plugin without needing to uninstall the previous version first. Chattree detects the existing plugin ID, displays the version transition (v1.0.0 → v1.1.0), and performs an in-place update (allowUpdate: true) that preserves the plugin's installedAt timestamp, user settings, private key-value storage, and SQLite database. Duplicate filename suffixes added by browsers or file managers (such as my-plugin (1).chattree-plugin or my-plugin - copia.chattree-plugin) are automatically normalized during import.Both distribution channels are backed by a persistent anti-downgrade watermark enforced in the mobile client runtime (PluginStateStore):
v1.0.0 after having installed v2.0.0) is rejected with a SecurityException:
"Degradación de versión rechazada: La versión "1.0.0" es inferior a la versión máxima registrada históricamente ("2.0.0")."
v2.0.0 → v2.0.0) is supported for repair or re-synchronization, but downgrades are strictly prevented to eliminate rollback attacks.Chattree commits to:
runtimeApiVersion increment.schemaVersion: 1 parseable indefinitely.Plugins built today against runtimeApiVersion: "1.0.0" will continue working
in future Chattree versions until a documented breaking release.