Package metadata schema

This page documents the schema mx publish produces for the registry's discovery index plus the local-registry index entry schema.

`IPackageDiscoveryMetadata`

projects/matrix-3/packages/mx-cli/src/utils/discovery-extractor.ts:35-47:

interface IPackageDiscoveryMetadata {
  readonly packageName: string;
  readonly version: string;
  readonly displayName?: string;
  readonly description?: string;
  readonly declaredKind?: string;
  readonly inferredKind: string;
  readonly tags: readonly string[];
  readonly capabilities: readonly string[];
  readonly permissions: JsonRecord | null;
  readonly webapp?: IWebappDiscoveryMetadata;
  readonly components: readonly IComponentDiscoveryMetadata[];
}

Field	Source	Notes
`packageName`	`matrix.json:name`	Required
`version`	`package.json:version`	Required
`displayName`	`matrix.json:displayName` (or alternate)	Advisory
`description`	`matrix.json:description`	Advisory
`declaredKind`	`matrix.json:type` if present	`webapp`/`service`/`library` by convention
`inferredKind`	derived from manifest shape	When `declaredKind` is absent
`tags`	static `tags` on root or component classes, plus manifest hints	Used for search
`capabilities`	static `capabilities` on classes (advisory today)
`permissions`	snapshot of `matrix.json:permissions`
`webapp`	when `matrix.json:webapp` present	See below
`components[]`	per `components[]` plus class introspection	See below

`IWebappDiscoveryMetadata`

interface IWebappDiscoveryMetadata {
  readonly appName: string;
  readonly routePrefix?: string;
  readonly displayName?: string;
  readonly icon?: string;
  readonly navOrder?: number;
  readonly description?: string;
  readonly shells: readonly string[];
}

routePrefix is /apps/<appName>/. shells typically ["platform", "edge"].

`IComponentDiscoveryMetadata`

interface IComponentDiscoveryMetadata {
  readonly type: string;
  readonly exportName?: string;
  readonly mount?: string;
  readonly surface?: string;
  readonly description?: string;
  readonly kind?: string;
  readonly accepts: readonly string[];
  readonly emits: readonly string[];
  readonly skills: readonly string[];
  readonly tags: readonly string[];
  readonly capabilities: readonly string[];
}

accepts/emits/skills/tags/capabilities are merged from the manifest entry plus the static contract on the class. The class wins on conflict. description/kind come from the static contract when present.

Local-registry index entry

For directory-backed registries (packages/mx-cli/src/utils/registry-store.ts):

interface IRegistryIndex {
  readonly packages: Record<string, IRegistryPackageEntry>;
}

interface IRegistryPackageEntry {
  readonly versions: Record<string, IRegistryVersionEntry>;
}

interface IRegistryVersionEntry {
  readonly tarballPath: string;
  readonly publishedAt: string;
  readonly publishedBy: string;
}

Stored at <registry-root>/index.json. tarballPath is absolute on disk; publishedAt is ISO-8601; publishedBy is the username from the credential record at publish time.

The discovery metadata for the same version is written next to the tarball (<registry-root>/<scope>/<name>/<version>/discovery.json).

npm-compatible registries

For HTTP-backed npm registries the metadata is whatever the registry serves. The Gitea-backed HiveCast registry (and any other npm-compatible) sends:

The npm package document with name, versions[<v>], dist-tags, time, etc.
Per-version: dist.tarball (URL), dist.shasum, dist.integrity.

mx publish writes the discovery metadata to the local index when publishing to a directory-backed registry; for npm registries, the discovery metadata extension is registry-specific. HiveCast's Gitea endpoint stores it as an auxiliary JSON document; other registries may not store it at all.

Package metadata schema ​

IPackageDiscoveryMetadata ​

IWebappDiscoveryMetadata ​

IComponentDiscoveryMetadata ​

Local-registry index entry ​

npm-compatible registries ​