Skip to content
ReferenceForDeveloper⏱ About 8 min

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 ​

  • id is unique on the install and never reused; it's also your permission prefix (<id>.<action>).
  • version is SemVer and immutable: any change is a new version.
  • builder modules may not have api, hooks, a ui.bundle, component routes, or the app data connection.
  • source modules must be signed (signature); files lists the sha256 of every file. Both are written by module:package / module:stamp: never by hand, and never committed.
  • Every menu[].route must be one of the ui.routes[].path.
  • private visibility needs owner_tenant_id.
  • overridable may not cover identity, trust, API, data, permissions or settings fields.

Fields ​

FieldTypeRequiredNotes
idstringyespattern ^[a-z][a-z0-9-]{1,47}$
versionstringyesa SemVer version such as 1.2.0; at most 32 characters
kindcore | source | builderyescore = ships with the platform; source = optional PHP+Vue module from the repo, signed; builder = data-only, uploadable.
systembooleancore only: always enabled, cannot be disabled.
titlestringyesat most 64 characters
descriptionstring
owner_tenant_idinteger or nullnull = platform-owned/shared; set = only that tenant may install.; from 1
extendsone of severalVariant base; version is the exact base version forked from.
visibilityplatform | listed | private
requiresarray of objectsSemVer ranges; id "platform" = core platform version.
requires[].idstringyespattern ^[a-z][a-z0-9-]{1,47}$
requires[].rangestringyesa SemVer range such as ^2.0 or >=1.2 <2; at most 64 characters
coexistbooleanVariant and base may both be enabled in one tenant.
scope_verifiedbooleanSet after the module passes the tenant-scope lint.
apiobject
api.entrystringpattern ^[A-Za-z0-9_][A-Za-z0-9._-]*(/[A-Za-z0-9_][A-Za-z0-9._-]*)*$; at most 255 characters
api.routerstringpattern ^[A-Za-z_][A-Za-z0-9_]*$
api.prefixesarray of strings
api.default_permissionstring or nullpattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters
api.public_pathsarray of strings
uiobject
ui.bundleone of several
ui.routesarray of objects
ui.routes[].pathstringyespattern ^/[A-Za-z0-9_:./-]*$; at most 120 characters
ui.routes[].componentstringpattern ^[A-Za-z_$][A-Za-z0-9_$]*$
ui.routes[].builder_pagestringpattern ^[a-z][a-z0-9_]{0,63}$
ui.routes[].typeview | classic | externaldefault 'view'
ui.routes[].titlestringat most 64 characters
ui.routes[].permissionstring or nullpattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters
ui.widgetsarray of objects
ui.widgets[].idstringyespattern ^[a-z0-9][a-z0-9_-]{0,47}$
ui.widgets[].titlestringyesat most 64 characters
ui.widgets[].componentstringyespattern ^[A-Za-z_$][A-Za-z0-9_$]*$
ui.widgets[].props_schemaobject
menuarray of objects
menu[].keystringyespattern ^[a-z0-9][a-z0-9_-]{0,47}$
menu[].titlestringyesat most 64 characters
menu[].routestringyespattern ^/[A-Za-z0-9_:./-]*$; at most 120 characters
menu[].parentstring or null
menu[].iconstringat most 64 characters
menu[].sortinteger
menu[].permissionstring or nullpattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters
menu[].badgestringAPI 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_handlersarray of items
permissionsarray of objects
permissions[].keystringyespattern ^[a-z][a-z0-9-]{1,47}\.[a-z0-9][a-z0-9_.-]*$; at most 64 characters
permissions[].labelstringyesat most 128 characters
permissions[].scopetenant | platformyes
permissions[].default_groupsarray of items
dataobject
data.connectionapp | inventory | moduleyes
data.tablesarray of objects
data.tables[].namestringyespattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
data.tables[].scopetenant_column | tenant_db | tenant_prefix | global_readonlyyes
data.tables[].ownedboolean
data.tables[].piiboolean
data.migrationsarray of strings
settings_schemaobjectJSON 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.typeanyyes
settings_schema.titlestring
settings_schema.descriptionstring
settings_schema.propertiesobject
overridablearray of stringsJSON Pointer prefixes a tenant override may patch. Identity, trust, API, data, permission and settings-schema fields are never overridable.
x-configobject
x-entitlementmarketplaceWho 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.
hooksobject
hooks.classstringyespattern ^[A-Za-z_][A-Za-z0-9_]*(\\[A-Za-z_][A-Za-z0-9_]*)*$
toolshedobject
toolshed.toolsarray of objects
toolshed.tools[].idstringyespattern ^[a-z0-9][a-z0-9_.-]{0,63}$
toolshed.tools[].titlestringyesat most 64 characters
toolshed.tools[].kindremote | bundledyes
toolshed.tools[].pathstring
toolshed.tools[].page_contextsarray of objects
toolshed.tools[].min_shellstring
toolshed.tools[].permissionstring or nullpattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters
builderobjectbuilder kind only: package layout globs.
builder.pagesstringa file pattern such as pages/*.json; at most 255 characters
builder.queriesstringa file pattern such as pages/*.json; at most 255 characters
builder.workflowsstringa file pattern such as pages/*.json; at most 255 characters
builder.tablesstringa file pattern such as pages/*.json; at most 255 characters
filesobjectsha256 of every package file except module.json and the signature.
signatureobjectEd25519 over ModuleManifest::canonicalJson (manifest without "signature").
signature.alganyyes
signature.key_idstringyespattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
signature.sigstringyespattern ^[A-Za-z0-9+/]+={0,2}$
dashboardobjectQuick 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.linksarray of objectsat most 8
dashboard.links[].labelstringyesat most 64 characters
dashboard.links[].routestringyespattern ^/[A-Za-z0-9_:./-]*$; at most 120 characters
dashboard.links[].iconstringpattern ^mdi-[a-z0-9-]{1,60}$
dashboard.links[].permissionstring or nullpattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$; at most 64 characters
dashboard.statsarray of objectsat most 8
dashboard.stats[].keystringyespattern ^[a-z][a-z0-9_]{0,47}$
dashboard.stats[].labelstringyesat most 64 characters
dashboard.stats[].connectionapp | inventoryyes
dashboard.stats[].tablestringyespattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
dashboard.stats[].permissionstring or nullpattern ^[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.