The manifest

The manifest is the one binding description of an app: defineAppManifest in the SDK, the check at load time, and the storage in the catalog all read exactly the same shape. The tables list each field with whether it is required, its format, and its effect. Examples follow below.

The fields#

unlocks and connects are omitted rather than set empty: an empty field would shift the canonical hash of every existing version although nothing has changed.

The compatibility block#

defineAppManifest requires the block both in the type and at runtime. Without it, the function throws with a sentence that names the three fields. Each list names a value at most once.

The translations block#

The texts of the manifest are written in German, the required language. Each additional language lives under translations as its own block, which carries texts only: displayName and description, store (tagline, long text, features, and setup steps in the order of the German ones), widgets by identifier with name, description, and variants by view, resources by identifier, permissions by key, dataAccess.external in the order of the services, and legal.disclaimerSummary. Identifiers, values, and rules never appear in a block.

A block is either complete or absent: defineAppManifest checks it with appManifestTranslationIssues() and throws at build time, naming the location. The store answers in the language that the portal requests and falls back to German. English terms follow the portals: display, never screen, and the video wall is called video wall. pnpm app:check <id> checks the texts of both languages against the house rule, in the Texte line.

The legal block#

A new disclaimerKey makes a release subject to consent: as soon as the new version is published as stable, the installation moves to Update waiting. Anyone who changes the substance of the notice therefore bumps the key, in the same pass as the short summary, the full text, and the app version. The platform silently adopts a reworded short summary under the same key. A manifest change without a version bump does not reach existing installations.

What is not in the manifest#

• Fetchers and jobs. An app declares them as decorators on classes in its backend (@Fetcher, @JobHandler, @WidgetResolver), and the platform discovers them at startup. The manifest remains a pure data format.
• Whether a load error aborts startup. That is a property of the installation and lives in the server configuration of the operations side. critical in the manifest is only a report.

Example: the manifest of the Pharmacies on duty app (abridged)#

import { defineAppManifest, RENDERER_HOST_RANGE } from '@szenera/apps-sdk/manifest';

export const manifest = defineAppManifest({
  id: 'pharmacies-on-duty',
  version: '1.3.0',
  displayName: 'Notdienst',
  description:
    'Zeigt die Apotheken im Notdienst rund um Ihren Standort, regelmäßig aktualisiert für ganz Deutschland.',
  tier: 'pro',
  category: 'geschaeft',
  vertical: 'pharmacy',
  schemaName: 'apps_pharmacies_on_duty',
  apiCompatibility: { appsSdk: '^0.2.0', rendererHost: RENDERER_HOST_RANGE },
  widgets: [PharmaciesOnDutyDisplayWidget],
  resources: [
    { ...PharmaciesOnDutyLocationResource, slug: 'locations' },
    { ...PharmaciesOnDutyScheduleResource, slug: 'schedules' },
  ],
  permissions: {
    tenant: [
      {
        key: 'pharmacies-on-duty.location.read',
        label: 'Standorte lesen',
        description: 'Hinterlegte Apotheken-Standorte ansehen, für die Notdienstpläne geladen werden.',
        defaultRoles: ['OWNER', 'MANAGER', 'MEMBER'],
      },
      // … further permissions for the team …
    ],
    platform: [
      {
        key: 'pharmacies-on-duty.crawler.config',
        label: 'Crawler konfigurieren',
        description: 'Betreiber-Recht: Quellen, Abrufintervalle und Parser des Notdienst-Crawlers einstellen.',
        defaultRoles: [],
      },
    ],
  },
  publisher: { name: 'Szenera' },
  signing: 'required',
  legal: {
    disclaimerKey: 'notdienst.bedingungen.v1',
    disclaimerSummary: 'Notdienstangaben stammen aus öffentlichen Verzeichnissen … und werden ohne Gewähr angezeigt …',
    termsPath: '/app-bedingungen/notdienst',
    requireAcceptanceAt: 'install',
  },
  preview: { iconUrl: '/apps/pharmacies-on-duty/icon.svg' },
  dataAccess: {
    external: [
      {
        name: 'Öffentliche Notdienst-Verzeichnisse (u. a. aponet.de)',
        purpose: 'Wir rufen die Dienstpläne für Ihre Standorte ab und halten sie aktuell.',
        sends: 'Postleitzahl und Umkreis der Standorte, die Sie angelegt haben.',
      },
    ],
  },
  // The server fetches the duty schedules, and the display keeps the last state in its snapshot.
  compatibility: {
    hosts: ['szenera-os', 'fire-tv', 'tizen', 'webos', 'web-display'],
    orientations: ['landscape', 'portrait'],
    offline: 'last-known',
  },
});

Form validation and cross-field rules#

defineAppManifest validates the shape against the schema, applies default values (tier, critical, criticalForTenant, signing), requires the compatibility block, and throws on every shape error. Three rules that arise from several fields at once are checked only by the platform at load time: the appId of each widget must equal the id of the manifest, each resource must carry the app’s prefix, and no two widgets may share an identifier. A manifest that contradicts the schema is rejected by release creation with Manifest.ValidationFailed (HTTP 422).

Related#

• Widget, configuration, and preview — the widget definition in the widgets field.
• Data access, permissions, and terms — dataAccess, permissions, unlocks, connects, and legal in detail.
• Signing and the path into the catalog — what follows from signing at release and on the device.