Appearance
module.json reference
Required: id, version, kind, title. Unknown top-level fields are refused, except your own x-… fields. Check a manifest with php bin/console module:validate <dir>.
Rules worth knowing
idis unique on the install and never reused; it's also your permission prefix (<id>.<action>).versionis SemVer and immutable: any change is a new version.buildermodules may not haveapi,hooks, aui.bundle,componentroutes, or theappdata connection.sourcemodules must be signed (signature);fileslists the sha256 of every file. Both are written bymodule:package/module:stamp: never by hand, and never committed.- Every
menu[].routemust be one of theui.routes[].path. privatevisibility needsowner_tenant_id.overridablemay not cover identity, trust, API, data, permissions or settings fields.
Fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | pattern ^[a-z][a-z0-9-]{1,47}$ |
version | string | yes | a SemVer version such as 1.2.0; at most 32 characters |
kind | core | source | builder | yes | core = ships with the platform; source = optional PHP+Vue module from the repo, signed; builder = data-only, uploadable. |
system | boolean | core only: always enabled, cannot be disabled. | |
title | string | yes | at most 64 characters |
description | string | ||
owner_tenant_id | integer or null | null = platform-owned/shared; set = only that tenant may install.; from 1 | |
extends | one of several | Variant base; version is the exact base version forked from. | |
visibility | platform | listed | private | ||
requires | array of objects | SemVer ranges; id "platform" = core platform version. | |
requires[].id | string | yes | pattern ^[a-z][a-z0-9-]{1,47}$ |
requires[].range | string | yes | a SemVer range such as ^2.0 or >=1.2 <2; at most 64 characters |
coexist | boolean | Variant and base may both be enabled in one tenant. | |
scope_verified | boolean | Set after the module passes the tenant-scope lint. | |
api | object | ||
api.entry | string | pattern ^[A-Za-z0-9_][A-Za-z0-9._-]*(/[A-Za-z0-9_][A-Za-z0-9._-]*)*$; at most 255 characters | |
api.router | string | pattern ^[A-Za-z_][A-Za-z0-9_]*$ | |
api.prefixes | array of strings | ||
api.default_permission | string or null | pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters | |
api.public_paths | array of strings | ||
ui | object | ||
ui.bundle | one of several | ||
ui.routes | array of objects | ||
ui.routes[].path | string | yes | pattern ^/[A-Za-z0-9_:./-]*$; at most 120 characters |
ui.routes[].component | string | pattern ^[A-Za-z_$][A-Za-z0-9_$]*$ | |
ui.routes[].builder_page | string | pattern ^[a-z][a-z0-9_]{0,63}$ | |
ui.routes[].type | view | classic | external | default 'view' | |
ui.routes[].title | string | at most 64 characters | |
ui.routes[].permission | string or null | pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters | |
ui.widgets | array of objects | ||
ui.widgets[].id | string | yes | pattern ^[a-z0-9][a-z0-9_-]{0,47}$ |
ui.widgets[].title | string | yes | at most 64 characters |
ui.widgets[].component | string | yes | pattern ^[A-Za-z_$][A-Za-z0-9_$]*$ |
ui.widgets[].props_schema | object | ||
menu | array of objects | ||
menu[].key | string | yes | pattern ^[a-z0-9][a-z0-9_-]{0,47}$ |
menu[].title | string | yes | at most 64 characters |
menu[].route | string | yes | pattern ^/[A-Za-z0-9_:./-]*$; at most 120 characters |
menu[].parent | string or null | ||
menu[].icon | string | at most 64 characters | |
menu[].sort | integer | ||
menu[].permission | string or null | pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters | |
menu[].badge | string | API path of this module (under api.prefixes) answering GET {count}; the shell polls it at most once a minute and shows the number on this menu item.; pattern ^(/[A-Za-z0-9_][A-Za-z0-9_.-]*)+$; at most 128 characters | |
menu[].replaces_handlers | array of items | ||
permissions | array of objects | ||
permissions[].key | string | yes | pattern ^[a-z][a-z0-9-]{1,47}\.[a-z0-9][a-z0-9_.-]*$; at most 64 characters |
permissions[].label | string | yes | at most 128 characters |
permissions[].scope | tenant | platform | yes | |
permissions[].default_groups | array of items | ||
data | object | ||
data.connection | app | inventory | module | yes | |
data.tables | array of objects | ||
data.tables[].name | string | yes | pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ |
data.tables[].scope | tenant_column | tenant_db | tenant_prefix | global_readonly | yes | |
data.tables[].owned | boolean | ||
data.tables[].pii | boolean | ||
data.migrations | array of strings | ||
settings_schema | object | JSON Schema subset (ModuleSettings / SchemaForm.vue): object of string, number, integer, boolean or array-of-string settings with title, description, default, enum, minimum/maximum, minLength/maxLength, format uri|email. x-secret: stored sealed, write-only in UI. x-tenant-editable: false = platform-only. Any other keyword is rejected at register time. | |
settings_schema.type | any | yes | |
settings_schema.title | string | ||
settings_schema.description | string | ||
settings_schema.properties | object | ||
overridable | array of strings | JSON Pointer prefixes a tenant override may patch. Identity, trust, API, data, permission and settings-schema fields are never overridable. | |
x-config | object | ||
x-entitlement | marketplace | Who switches the module on and off for an organization. "marketplace": the organization's marketplace subscription does (ModuleRegistry::entitlementOf); organization administrators get 403 managed_by_marketplace on install, enable, disable, version changes and fork. Leave the key out otherwise. | |
hooks | object | ||
hooks.class | string | yes | pattern ^[A-Za-z_][A-Za-z0-9_]*(\\[A-Za-z_][A-Za-z0-9_]*)*$ |
toolshed | object | ||
toolshed.tools | array of objects | ||
toolshed.tools[].id | string | yes | pattern ^[a-z0-9][a-z0-9_.-]{0,63}$ |
toolshed.tools[].title | string | yes | at most 64 characters |
toolshed.tools[].kind | remote | bundled | yes | |
toolshed.tools[].path | string | ||
toolshed.tools[].page_contexts | array of objects | ||
toolshed.tools[].min_shell | string | ||
toolshed.tools[].permission | string or null | pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters | |
builder | object | builder kind only: package layout globs. | |
builder.pages | string | a file pattern such as pages/*.json; at most 255 characters | |
builder.queries | string | a file pattern such as pages/*.json; at most 255 characters | |
builder.workflows | string | a file pattern such as pages/*.json; at most 255 characters | |
builder.tables | string | a file pattern such as pages/*.json; at most 255 characters | |
files | object | sha256 of every package file except module.json and the signature. | |
signature | object | Ed25519 over ModuleManifest::canonicalJson (manifest without "signature"). | |
signature.alg | any | yes | |
signature.key_id | string | yes | pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ |
signature.sig | string | yes | pattern ^[A-Za-z0-9+/]+={0,2}$ |
dashboard | object | Quick links and Metric sources the module adds to the built-in dashboard while it is enabled for an organization. Checked in PHP only: each links[].route is one of ui.routes; each stats[].key starts with the module id ("" for "-"); an inventory stat counts a tenant_column table of data.tables, an app stat a table whose name starts with ac plus the module id ("_" for "-"). | |
dashboard.links | array of objects | at most 8 | |
dashboard.links[].label | string | yes | at most 64 characters |
dashboard.links[].route | string | yes | pattern ^/[A-Za-z0-9_:./-]*$; at most 120 characters |
dashboard.links[].icon | string | pattern ^mdi-[a-z0-9-]{1,60}$ | |
dashboard.links[].permission | string or null | pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters | |
dashboard.stats | array of objects | at most 8 | |
dashboard.stats[].key | string | yes | pattern ^[a-z][a-z0-9_]{0,47}$ |
dashboard.stats[].label | string | yes | at most 64 characters |
dashboard.stats[].connection | app | inventory | yes | |
dashboard.stats[].table | string | yes | pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ |
dashboard.stats[].permission | string or null | pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters |
Your own fields
x-config (configuration that organization overrides may patch), x-changelog (shown in the upgrade preview) and x-grant-from-menus (grant new permission keys to existing groups) are read by BMA. Other x-… fields are yours.