Manifest schema

This page is the authoritative reference for matrix.json, mirrored from validateManifestForMxCli in projects/matrix-3/packages/mx-cli/src/utils/manifestValidator.ts.

Run mx validate --json to see the validator's output for any package.

Top-level fields

Path	Required	Type	Diagnostic code
name	yes	non-empty string	MXPKG_NAME_INVALID
version	yes	non-empty string	MXPKG_VERSION_INVALID
description	no	string	—
class	no	string	—
namespace	no	string	—
runtime	yes (object)	see below	MXPKG_RUNTIME_INVALID
root	no (object)	see below	—
webapp	no (object)	see below	—
http	no (object)	see below	—
consumes	no (array)	see below	—
exports	no (array of strings)	—	—
components	yes (array, may be empty)	see below	MXPKG_COMPONENTS_NOT_ARRAY
permissions	yes (object)	see below	MXPKG_PERMISSIONS_*
install	no (object)	see below	MXPKG_INSTALL_*
config	no (object)	conventional only	—

runtime

Path	Required	Type
runtime.language	yes	non-empty string
runtime.entry	yes	non-empty string
runtime.browserEntry	no	string
runtime.bootstrapEntry	no	string
runtime.environments	no	string[] (advisory)
runtime.executionClassCompatibility	no	string[] (advisory)

A missing or empty runtime.language/runtime.entry triggers MXPKG_RUNTIME_INVALID: runtime.language and runtime.entry are required.

permissions

Path	Required	Type / allowed values
permissions.fsPolicy	yes	one of none, matrix-only, project-readonly, project-readwrite, global-readonly (MXPKG_PERMISSIONS_FSPOLICY_INVALID)
permissions.hostApi	no	one of none, same-origin (MXPKG_PERMISSIONS_HOSTAPI_INVALID)
permissions.network	no	boolean (MXPKG_PERMISSIONS_BOOLEAN_INVALID)
permissions.subprocess	no	boolean (same code)
permissions.env	no	boolean (same code)

components[]

Validator at manifestValidator.ts:158-244.

Path	Required	Type / allowed values	Diagnostic code
components[].type	yes	non-empty string	MXPKG_COMPONENT_TYPE_INVALID
components[].export	no	non-empty string when present	MXPKG_COMPONENT_EXPORT_INVALID
components[].mount	no	non-empty string when present	MXPKG_COMPONENT_MOUNT_INVALID
components[].autoStart	no	boolean	MXPKG_COMPONENT_AUTOSTART_INVALID
components[].props	no	object	MXPKG_COMPONENT_PROPS_INVALID
components[].fsPolicy	no	same enum as permissions.fsPolicy	MXPKG_COMPONENT_FSPOLICY_INVALID
components[].surface	no (advisory)	string (headless/browser by convention)	—
components[].description	no (advisory)	string	—
components[].accepts	no (advisory)	string[]	—
components[].emits	no (advisory)	string[]	—

A non-array components triggers MXPKG_COMPONENTS_NOT_ARRAY. A non-object element triggers MXPKG_COMPONENT_NOT_OBJECT for that index.

webapp

Read by packages/mx-cli/src/utils/webapp-manifest.ts. Not enforced by the CLI validator, but consumed by mx run --serve and the discovery extractor.

Path	Type / convention
webapp.distDir	string, relative to package root
webapp.entry	string, file inside distDir (e.g. index.html)
webapp.appName	string slug (URL component)
webapp.displayName	string
webapp.icon	string
webapp.navOrder	number
webapp.description	string
webapp.shells	string[] (platform, edge)
webapp.base	string (relative is the supported value today)

http

Read by system-gateway-http. Not enforced by the CLI validator.

"http": {
  "routes": [{
    "export": "MyHttpSurface",
    "prefixes": ["/api/foo/", "/api/bar/"]
  }]
}

consumes

Advisory list of service contracts the package depends on. Each entry has contract (string), required (boolean), bindingKey (string).

install

Path	Type	Diagnostic code
install	object	MXPKG_INSTALL_INVALID if not an object
install.<phase>	object	MXPKG_INSTALL_HOOK_INVALID if not an object
install.<phase>.script	non-empty string	MXPKG_INSTALL_HOOK_SCRIPT_INVALID
install.<phase>.description	optional string	—

Phases: validate, migrate, seed, verify. Run in that order during mx install.

root (alternative to components[])

Convention used by packages that have one primary actor:

"root": {
  "type": "SystemRootActor",
  "export": "SystemRootActor",
  "mount": "system",
  "surface": "headless",
  "description": "...",
  "accepts": ["system.status", "system.children"]
}

mx publish's preflight requires the package declare at least one of: root, non-empty components[], webapp, or matrix.service.json factory. The validator checks all four together at publish time (packages/mx-cli/src/commands/publish.ts:62-83).

See also

• Authoring → Package manifest
• Reference → Package metadata schema

Source: projects/matrix-3/packages/mx-cli/src/utils/manifestValidator.ts is the authoritative validator; packages/mx-cli/src/commands/validate.ts is its CLI face.