Note: This document serves as a supplementary explanation of the MiniApp Packaging spec. If there is any inconsistency with the spec, you should consider the spec to be authoritative.
- Yongjing Zhang (Huawei)
A MiniApp Package is a ZIP-based container file that wraps a set of files (JS code, components, resources, configurations, styles) comprising the whole MiniApp.
It can be delivered to a user agent through different channels (e.g., web, app store, offline), then rendered/executed by the hosting platform.
A MiniApp Package contains all necessary information used by a user agent to properly check, load, and execute the MiniApp. A standardized format is essential so that a MiniApp package generated by different developers or tools can be deployed on various hosting platforms (e.g., super-apps and native-OS frameworks) in a compatible and consistent way.
The spec shall define the following aspects to ensure interoperability:
- the minimum set of files for a MiniApp to be runnable;
- the optional files for enhanced features;
- a well-defined file and directory structure;
- pre-defined file names and naming convention;
- parsing and validity check mechanism;
- the overall file format (and extension name) of the package;
- the corresponding MIME type for internet exchange.
Following the common practice of mobile app packaging (such as Android APK), the MiniApp package is designed as a specialized ZIP file, which has its file extension name (.ma) and a dedicated MIME type (application/miniapp-pkg+zip - to be registered with IANA).
The package can be treated as a regular .zip file in some cases (i.e., a ZIP parser may open and read the MiniApp package without following the MiniApp Packaging spec). However, having the dedicated file extension name and MIME Type gives a way for a hosting platform or a package loader to do pre-checking or content negotiation before loading/downloading the package.
A MiniApp package requires a homogeneous file system organization:
- manifest.json: A JSON-based file responsible for the global configuration of the app, as an extension of the Web App Manifest. (See MiniApp Manifest)
- app.js: Document with scripts defining the main application logic and responsible for the life-cycle management (see MiniApp Lifecycle)
- app.css: The global/default application stylesheet.
- pages: A reserved directory that contains all page-related resources. It may have sub-directories to organize different pages. Each page may have the following associated files:
- *.js: The page scripts (i.e., app logic of the page)
- *.html: The page layout (the concrete format is under discussion)
- *.css: The page-specific style
- common: A reserved directory that contains common resources (i.e., images, scripts, UI components, templates) that can be (re)used by one or multiple MiniApp pages/widgets. It may have sub-directories for an efficient organization. (Details are for further study.)
Note: As the MiniApp Packaging spec is still under development, the content listed above is not complete yet and is subject to further change.
A MiniApp package should guarantee integrity and trustworthiness in the app distribution. So, a MiniApp package may include one or more digital signatures with integrity mechanisms and certificates that enable verifying authors (e.g., the MiniApp developer) and distributors (e.g., an application marketplace). (See more details in the spec)
User agents may require specific digital signature mechanisms, depending on the use case and MiniApp environment, so the specification does not recommends concrete encryption methods or technologies. The specification will include informative examples of various technologies to be used, such as RFC5652 (PKCS#7) and the APK Signature Scheme v2).
One typical illustrative example of a MiniApp package is given in the spec.
There are already some other packaging technologies specified for different purposes, such as Widgets (obsolete), WICG WebPackage (WPACK) and its obsolete version, and Lightweight Packaging Format (LPF). They are designed based on different archive formats (e.g., ZIP and CBOR) and use different signature mechanisms (e.g., XMLDSIG-based, HTTP-based), and contain different types of contents (e.g., web pages, HTTP exchanges, digital publications). Such differences result from the diversity of the environment assumptions and the technical requirements of individual technologies.
The MiniApp package also has unique assumptions and requirements that cannot be addressed directly by existing technologies. It is essentially a mobile application container, designed to pack all required application materials (e.g., pages, layouts, UI components, resources, scripts, and configurations) to be deployed and executed by various application user agents (e.g., "Mini Program" [1][2][3] and Quick App), rather than to pack web contents or digital publications to be loaded by browsers or e-book readers.
The following analysis summarizes the main reasons why existing packaging technologies cannot meet the needs of MiniApp packaging:
- WPACK: It is intended to pack a collection of web resources in terms of HTTP exchanges (including HTTP requests, responses, signatures, and other metadata) so that a browser can load them locally and recover the web transaction states securely without accessing the origin. To achieve this, an HTTP-specific signature mechanism is defined, which is apparently not suitable for MiniApp, which does not rely on HTTP exchanges. Moreover, WPACK proposes to define a new CBOR-based archive format instead of using ZIP for web-specific reasons that do not apply to MiniApp. For instance, ZIP resources are file-based, so they are not efficient for HTTP response headers in WPACK but can serve MiniApp very well and are already used widely in mobile application packaging implementations (e.g., Android APK, QuickApp, MiniProgram).
- Web Package (obsolete): It is an unfinished work as the ancestor of WPACK. It chooses not to use ZIP but defines a new Streamable Package Format for specific reasons that are not seen by MiniApp. Again, it is designed as closely coupled with HTTP (headers) which is not suitable for MiniApp.
- Widgets (obsolete): It is an old implementation of Packaged Web Apps called Widgets. It is ZIP-based but has specific file/folder structure and naming constraints, and it uses XML-based configuration documents. These constraints are not compatible with MiniApp. In addition, it uses XMLDSIG for the digital signature, which can only protect the signed files but not the entire package file itself. One can add/remove signature files, add other files or blocks into the ZIP package, or alter the ZIP metadata without being noticed. Such vulnerability is not acceptable by MiniApp.
- LPF: It is a lightweight ZIP-based packaging format that contains digital publication materials. It mandates publication-specific files (i.e.,
publication.json,index.html) that are not needed by a MiniApp, while misses MiniApp specific files likemanifest.jsonandapp.js. Also, it does not cover the security concerns, such as the integrity protection of the whole package that a MiniApp addresses.
The following table shows a detailed comparison between a MiniApp package and other packaging technologies:
| Technology | Client Platform | Content | Web Dependency | Format | Digital Signature |
|---|---|---|---|---|---|
| MiniApp | Super-App, OS, or Browser* | Application-resources (e.g., app logics, page layouts, UI components – not necessarily h5-based) | No (may or may not use web resources) | ZIP-based | PKCS#7 |
| WPACK | Browser | Web content (HTTP exchanges) | Yes (a web origin is always assumed, even offline) | CBOR-based | HTTP header extension |
| WebPackage (old) | Browser | Web content | Yes (a web origin is always assumed, even offline) | Streamable Package Format (.pack) | n/a |
| Widgets | Browser, OS | Widget files (html start files, XML configuration, icons ...) | No (may or may not use web resources) | ZIP-based | XMLDSIG-based |
| LPF | e-Readers | Digital publications, configuration | No | ZIP-based | unknown* |
Note:
*in the table above denotes the feature that is under discussion/development.
Although MiniApp leverages popular web front-end technologies like JavaScript and CSS, a MiniApp is closer to a native app than a snapshot of a web-content collection. Moreover, existing web packaging technologies cannot cover the requirements of MiniApp, so a dedicated MiniApp Packaging specification needs to be developed.