Manifest des Artefaktpakets

Schema-ID: artifact-package@1 Maschinenlesbares Schema: artifact-package.schema.json Dateiname im Archiv: parsware.json, im Stammverzeichnis des Archivs

Das, was aus einem Ordner mit Bundler-Ausgabe etwas macht, das die Plattform annehmen kann. npm run pack schreibt es neben die Build-Ausgabe und packt es mit ihr in das Zip-Archiv; die Plattform liest es beim Upload, und ein von Hand zusammengestelltes Archiv wird nach genau derselben Regel abgewiesen wie ein generiertes (das Prinzip des einen Validierungspfads, Abschnitt 6.7).

Warum es existiert

Die Registrierung fragte einen Ersteller früher nach sechs Feldern, von denen zwei aus einer Bundler-Konfiguration abgeschrieben wurden: der Module-Federation-Scope und das bereitgestellte Modul. War eines davon falsch, zeigte sich immer dasselbe Symptom – das Steuerelement lud nicht –, ohne Hinweis darauf, welches der beiden falsch war. Der Build kennt beide bereits, also schreibt er sie auf.

Aufbau

Feld	Typ	Pflicht	Hinweise
formatVersion	integer	ja	Muss genau 1 sein. Ein const statt eines Mindestwerts, damit ein Archiv aus einem künftigen Format mit einer klaren Meldung abgewiesen wird, statt nach heutigen Regeln gelesen zu werden und an weniger offensichtlicher Stelle zu scheitern.
kind	string	ja	CustomControl. Benutzerdefinierte Apps kommen zu dieser Aufzählung hinzu, sobald sie das Paket übernehmen – sie werden denselben Speicher, denselben Cache und denselben Auslieferungsendpunkt nutzen und sich nur in den artspezifischen Feldern dieses Manifests unterscheiden.
logicalName	string	ja	Mit Herausgeberpräfix, Snake-Case in Kleinbuchstaben (z. B. par_signature_pad). Wird beim Upload gegen das Herausgeberpräfix der besitzenden Lösung geprüft, sodass ein Präfix nicht von einem Archiv aus anderer Quelle beansprucht werden kann.
displayName	string	ja	Lesbarer Name, der in der Feldpalette des Formulardesigners angezeigt wird.
description	string | null	nein	Kurzbeschreibung, höchstens 512 Zeichen.
version	string	ja	Dreiteilige Version (1.2.3), die eigene npm-Version des Steuerelements. Wird zur Diagnose festgehalten und einem Ersteller angezeigt, der prüft, ob das Installierte dem Gebauten entspricht; sie steuert nichts.
scope	string	ja	Der Scope des Module-Federation-Containers, aus der Federation-Konfiguration des Builds gelesen.
module	string	ja	Der Pfad des bereitgestellten Moduls (z. B. ./Control), aus der exposes-Zuordnung der Federation-Konfiguration gelesen.
entry	string	ja	Die Einstiegsdatei des Containers im Archiv (z. B. remoteEntry.js). Ein reiner Dateiname, kein Pfad: Er benennt eine Datei im Stammverzeichnis des Archivs, das zugleich der Basispfad ist, von dem die Plattform die asynchronen Chunks des Artefakts ausliefert.
substitutesFor	string[]	ja bei CustomControl	Die Datentypfamilien von Feldern, an die das Steuerelement gebunden werden kann. Muss exakt der Aufzählung von custom-control-manifest@1 entsprechen.
requestedScopes	string[]	ja bei CustomApp	Die OAuth-Scopes, die eine benutzerdefinierte App als benötigt deklariert und die beim Ausstellen ihres App Context Tokens angefordert werden (§6.3). Fehlt bei einem benutzerdefinierten Steuerelement, das keine deklariert – es läuft mit den Berechtigungen der Person, die es verwendet (§28).

Woher die Werte stammen

Aus zwei Quellen, und keine rät die Hälfte der anderen:

• scope, module, entry werden aus der eigenen mf-manifest.json des Builds gelesen, weil der Bundler sie festlegt. @module-federation/vite erzeugt diese Datei nur mit der Konfiguration manifest: true, die standardmäßig ausgeschaltet ist – deshalb schaltet jedes Parsware-Steuerelement sie ein, und der Packer weigert sich zu raten, wenn sie fehlt.
• logicalName, displayName, description, substitutesFor stammen aus einem parsware-Block in der package.json des Steuerelements, weil der Bundler von keinem davon je gehört hat. version ist die eigene version dieser Datei.

Was bewusst fehlt

Es gibt keine deklarierten Scopes und keine deklarierten Tabellen. Ein Artefakt läuft mit den Berechtigungen der Person, die es verwendet (§24); eine Scope-Liste auf dem Artefakt könnte dessen Benutzer also immer nur einschränken, nie erweitern.

Es gibt keine Remote-Entry-URL. Das Paket wird vom eigenen Ursprung der Plattform unter einem Pfad ausgeliefert, der aus der Umgebung und dem logischen Namen berechnet wird – genau das erlaubt es einem Steuerelement, innerhalb seiner Lösung zu wandern, statt von einem externen Host abgerufen zu werden.

Was die Plattform prüft

Beim Upload, bevor irgendetwas gespeichert wird:

1. Das Archiv liegt innerhalb der Obergrenze für die komprimierte Größe und ist ein lesbares Zip-Archiv;
2. es enthält nicht mehr als die konfigurierte Anzahl von Dateien und wird entpackt nicht größer als die konfigurierte Gesamtgröße (geprüft beim Lesen und nochmals beim Entpacken – die in einem Zip-Header angegebene Länge ist eine Behauptung, die das Archiv über sich selbst aufstellt);
3. jeder Eintragspfad ist relativ und sicher – .., ein absoluter Pfad sowie ein Windows-Laufwerks- oder UNC-Präfix werden abgewiesen statt bereinigt, denn ein Archiv, das einen Pfad außerhalb seines eigenen Ordners nennt, ist keines, das man stillschweigend reparieren sollte;
4. jede Datei hat eine Endung, die auf der Positivliste der Plattform für die Auslieferung steht;
5. parsware.json liegt im Stammverzeichnis und ist gemäß diesem Schema gültig;
6. kind passt zum Endpunkt, und die in entry genannte Datei ist tatsächlich vorhanden.

Verwandt

• Ein benutzerdefiniertes Steuerelement erstellen – eines schreiben und packen.
• Ein benutzerdefiniertes Steuerelement registrieren – das Paket hochladen.
• Manifest eines benutzerdefinierten Steuerelements – die gespeicherte Form, in die dieses Manifest eingeht.