This specification is a registry of supplementary members for the Web Application Manifest and the Web App Manifest - Application Information specifications that provide additional metadata to an application manifest to describe [=MiniApps=]. This JSON-based manifest file enables developers to set up basic information of a MiniApp, like identification, human-readable description, versioning data, and styling information. The MiniApp manifest also configures the routing of the pages and widgets that are part of a MiniApp.

MiniApp Manifest

A MiniApp manifest is a [[JSON]] document that extends and profiles the Web App Manifest [[APPMANIFEST]] and the Web App Manifest - Application Information [[MANIFEST-APP-INFO]], to describe metadata associated with a MiniApp.

This specification defines the set of metadata to describe MiniApps, extending the [[[APPMANIFEST]]] and the [[[MANIFEST-APP-INFO]]] by providing additional constraints and specific mechanisms to describe and set up MiniApps. The MiniApp Manifest directly reuses essential elements from these specifications (i.e., `name`, `short_name`, `description`, and `icons`), adding supplementary members that specifically affect MiniApps (e.g., `app_id`, `version`, `platform_version`, `device_type`, `pages`, `req_permissions`, and `widgets`) and their look and feel (e.g., `color_scheme` and `window`).

Conformance

A [=MiniApp manifest=] MUST contain the following members at its root:

Each [=image resource=] object within the [=MiniApp manifest's=] [=icons=] member MUST contain:

A [=MiniApp manifest=] MAY contain a [=widgets=] member at its root. This member MUST contain an array ([=list=]) of [=MiniApp widget resources=]. Each [=MiniApp widget resource=] object MUST contain the following members:

A [=MiniApp manifest=] MAY contain a [=req_permissions=] member at its root. This member MUST contain an array ([=list=]) of [=MiniApp permission resources=]. Each [=MiniApp permission resource=] object MUST contain the following member:

MiniApp user agents MAY implement vendor-specific extensions of the [=manifest=], supporting optional members.

Summary of Members

The following table shows a summary of the [=MiniApp manifest's=] members:

Members at root
Member Type Required Description
[=app_id=] [=string=] Yes MiniApp identifier
[=color_scheme=] [=string=] No MiniApp color scheme
[=description=] [=string=] No MiniApp description
[=device_type=] [=list=] No Supporting devices
[=dir=] [=string=] No Direction of texts
[=icons=] [=image resource=] [=list=] Yes MiniApp icons
[=lang=] [=string=] No MiniApp primary language
[=MiniApp manifest/name=] [=string=] Yes MiniApp name
[=pages=] [=list=] Yes Page routing information
[=MiniApp manifest/platform_version=] [=platform version resource=] Yes Platform version supported
[=req_permissions=] [=permission resource=] [=list=] No Required permissions
[=short_name=] [=string=] No MiniApp short name
[=version=] [=version resource=] Yes MiniApp version
[=widgets=] [=widget resource=] [=list=] No MiniApp widgets
[=window=] [=window resource=] No Window style
Members of [=image resource=] objects
([=icons=] [=list=])
Member Type Required Description
label [=string=] No Accessible text
sizes [=string=] No Resolution sizes of an icon
src [=string=] Yes Source of an icon
Members of [=platform version resource=] objects
([=platform_version=] [=ordered map=])
Member Type Required Description
[=MiniApp platform version resource/min_code=] number Yes Minimum platform version supported
[=MiniApp platform version resource/release_type=] [=string=] No Target platform version type
[=MiniApp platform version resource/target_code=] [=string=] No Target platform version code
Members of [=permission resource=] objects
([=req_permissions=] [=list=])
Member Type Required Description
[=MiniApp permission resource/name=] [=string=] Yes Permission name
[=reason=] [=string=] No Reason to request the permission
Members of [=version resource=] objects
([=version=] [=ordered map=])
Member Type Required Description
[=MiniApp version resource/code=] number Yes Version code
[=MiniApp version resource/name=] [=string=] Yes Version name
Members of [=widget resource=] objects
([=widgets=] [=list=])
Member Type Required Description
[=MiniApp widget resource/min_code=] number No Minimum platform version supported
[=MiniApp widget resource/name=] [=string=] Yes Widget name
[=path=] [=string=] Yes Widget path
Members of [=window resource=] objects
([=window=] [=ordered map=])
Member Type Required Description
[=auto_design_width=] [=boolean=] No Enables/disables auto-calculation of page's [=design_width=]
[=MiniApp window resource/background_color=] [=string=] No Window background color
[=background_text_style=] [=string=] No Background text style
[=design_width=] number No The baseline page design width
[=enable_pull_down_refresh=] [=boolean=] No Enable pull-to-refresh event
[=fullscreen=] [=boolean=] No Full screen display
[=navigation_bar_background_color=] [=string=] No Navigation bar background color
[=navigation_bar_text_style=] [=string=] No Text style of the navigation bar
[=navigation_bar_title_text=] [=string=] No Navigation bar title
[=navigation_style=] [=string=] No Navigation bar style
[=on_reach_bottom_distance=] number No Distance for pull-up bottom event triggering
[=orientation=] [=string=] No Screen orientation settings

Other [=application manifest=] members such as scope, theme_color, related_applications, prefer_related_applications, and shortcuts are not currently supported by MiniApp user agents.

Example

The following code represents a [=MiniApp manifest=] example:

        {
          "dir": "ltr",
          "lang": "en-US",
          "app_id": "org.example.miniapp",
          "name": "MiniApp Demo",
          "short_name": "MiniApp",
          "version": {
            "name": "1.0.1",
            "code": 11
          },
          "description": "A Simple MiniApp Demo",
          "icons": [
            {
              "label": "Red lightning",
              "src": "common/icons/icon.png",
              "sizes": "48x48"
            }
          ],
          "platform_version":{
            "min_code": 1,
            "release_type": "Beta1",
            "target_code": 2
          },
          "pages": [
            "pages/index/index",
            "pages/detail/detail"
          ],
          "window": {
            "background_color": "#ffffff",
            "fullscreen": false,            
            "navigation_bar_text_style": "black",
            "navigation_bar_title_text": "My MiniApp",
            "navigation_bar_background_color": "#f8f8f8"
          },
          "widgets": [
            {
              "name": "widget",
              "min_code": "2",
              "path": "widgets/index/index"
            }
          ],
          "req_permissions": [
            {
              "name": "system.permission.LOCATION",
              "reason": "To show user's position on the map"
            },
            {
              "name": "system.permission.CAMERA",
              "reason": "To scan a QR code"
            }
          ],
          "color_scheme": "light",
          "device_type": [
             "phone",
             "tv",
             "car"
          ]		  
        }
      

Web Application Manifest members

The [=MiniApp manifest=] uses the following essential [=application manifest=]'s members.

dir member

The [=MiniApp manifest's=] dir member, while specifying the base direction of the [=localizable members=] of the [=manifest=], also specifies the default base text direction of the whole MiniApp.

The [=dir=] member's value can be set to one of the text-directions as specified in [[APPMANIFEST]]. The text-direction values are the following:

"ltr"
Left-to-right text.
"rtl"
Right-to-left text.
"auto" (default)
No explicit directionality.

When [=processing a MiniApp manifest=], the process the dir member algorithm is used to process the dir member, according to the [[APPMANIFEST]] specification.

icons member

The [=MiniApp manifest's=] icons member describes images that serve as iconic representations of MiniApps. This member is a [=list=] of [=image resource=] [=ordered maps=].

As specified in [[IMAGE-RESOURCE]], an [=image resource=] consists of:

label
An optional [=string=] representing the accessible name of the image.
sizes
An optional [=string=] representing the sizes of the image, expressed using the same syntax as [^link^]'s [^link/sizes^] attribute.
src
A URL from where to obtain the image data.

When [=processing a MiniApp manifest=], the process image resources algorithm is used to process the icons member, according to the [[APPMANIFEST]] specification.

Developers are strongly encouraged to add a `label` unless the [=image resource=]’s accessible name can be inferred from an external label in its context.

lang member

The [=MiniApp manifest's=] lang member, while specifying the primary language of the [=localizable members=], also specifies the primary language of the whole MiniApp. This member is a [=string=] in the form of a language tag, a string that matches the production of a Language-Tag [[BCP47]], as defined in [[APPMANIFEST]].

When [=processing a MiniApp manifest=], the process the lang member algorithm is used to process the lang member, according to the [[APPMANIFEST]] specification.

name member

The [=MiniApp manifest's=] name member is the descriptive name of the application. This is the name directly displayed to the user. It is used as the display name of MiniApp along with the desktop icon and in the context of MiniApp management.

When [=processing a MiniApp manifest=], the process a text member algorithm is used to process the name member, according to the [[APPMANIFEST]] specification.

short_name member

The [=MiniApp manifest's=] short_name member provides a concise and easy-to-read name for a MiniApp. It can be used when there is insufficient space to display the full MiniApp name provided in [=MiniApp manifest/name=].

When [=processing a MiniApp manifest=], the process a text member algorithm is used to process the short_name member, according to the [[APPMANIFEST]] specification.

Application Information members

The following member is defined in the Web App Manifest - Application Information specification [[MANIFEST-APP-INFO]].

description member

The [=MiniApp manifest's=] description member provides a textual description for the MiniApp representing the purpose of the web application in natural language, as defined in [[MANIFEST-APP-INFO]]

To process the description member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["description"] is not a [=string=], return.
  2. Set |manifest|["description"] to |json|["description"].

Supplementary members

The following members are defined under the scope of the [=MiniApp manifest=], addressing specific aspects of MiniApp.

app_id member

The [=MiniApp manifest's=] app_id member is a [=string=] that identifies the MiniApp uniquely. This member is mainly used for package management, supporting the update and release process of MiniApp versioning.

The value of [=app_id=] is both case-sensitive and sensitive to different ways of encoding characters in Unicode. Consequently, two [=app_id=] values are equal only if they are encoded as the same sequence of code points.

One common practice for MiniApps is to use the reverse-domain-name-like convention used by the Java package naming convention (e.g., org.example.miniapp) under the following rule:

            appIdRule = name *("." name)
            name = ALPHA [*( ALPHA / DIGIT / "-" ) ( ALPHA / DIGIT)]
          

To process the app_id member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["app_id"] does not [=map/exist=], or if |json|["app_id"] is not a [=string=], return.
  2. Set |manifest|["app_id"] to |json|["app_id"].

color_scheme member

The optional [=MiniApp manifest's=] color_scheme member is a [=string=] that indicates the preferred color scheme of a MiniApp (i.e., "[=color_scheme/`auto`=]", "[=color_scheme/`light`=], or "[=color_scheme/`dark`=]"), overriding other configuration members of the [=window resource=] object, including [=MiniApp window resource/background_color=], [=background_text_style=], [=navigation_bar_text_style=], and [=navigation_bar_title_text=].

This member MUST contain one of the following color scheme values:

"auto"
The theme color is adapted to the system theme color.
"light"
For a light color scheme.
"dark"
For a dark color scheme.

MiniApp user agents MAY implement pre-defined styling resources, such as background colors, cover images, and icons for each color scheme. Also, developers MAY define customized stylesheets for each mode, using the prefers-color-scheme CSS media feature [[MEDIAQUERIES-5]].

To process the color_scheme member, given [=ordered map=] |json:JSON| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["color_scheme"] does not [=map/exist=],
    or if |json|["color_scheme"] is not a [=string=],
    or if |json|["color_scheme"] doesn't match one of the [=color scheme values=], return.
  2. Set |manifest|["color_scheme"] to |json|["color_scheme"].

device_type member

The optional [=MiniApp manifest's=] device_type member is a [=list=] of [=strings=] that indicates the type of devices on which the MiniApp is intended to run. The values of this member inform user agents if the MiniApp has been designed to properly run on specific platforms like smartphones, smart TVs, car head units, wearables, and other devices.

This member is used for device compatibility verification during the initialization process. By checking its value, the user agent decides if the MiniApp is suitable to be run on the platform in terms of compatibility of UI components, CSS support, and APIs. MiniApp user agents decide how to implement the platform's behavior if the verification process fails (e.g., stopping the initialization phase and refusing the installation or installing the MiniApp but rejecting the execution).

The list of possible values of the member is not specified in this document, enabling flexibility in the implementation and considering any device and use case. Some of the common values are: smartphone, tablet, tv, car, wearable, and iot.

To process the device_type member, given [=ordered map=] |json:JSON| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["device_type"] does not [=map/exist=], or if |json|["device_type"] is not a [=list=], return.
  2. Let |device_type:list| be a new empty [=list=].
  3. [=list/For each=] |item:string| of |json|["device_type"]:
    1. If |item| is not a [=string=], return.
    2. [=list/Append=] |item| to |device_type|.
  4. Set |manifest|["device_type"] to |device_type|.

pages member

The [=MiniApp manifest's=] pages member is a [=list=] of [=relative-url string=] used for specifying the collection of pages that are part of a MiniApp. Each item in the [=list=] represents a page identified by its [=page route=].

A MiniApp page route is the relative path and filename of a MiniApp page. When configuring the [=page routes=], developers MAY omit the extension of the file that defines the main component of the page (e.g., pages/mypage or pages/mypage.html).

The first item in the [=pages=] [=list=] defines the homepage or entry point of a MiniApp.

For compatibility with the Web platform, it is RECOMMENDED to use [=pages=] along with the Web application manifest's [=manifest/start_url=] and [=manifest/scope=] members. These members will be set with the following values:

  • [=manifest/start_url=] SHOULD be set with the same value of the first item in the [=pages=] member; and
  • [=manifest/scope=] SHOULD be set with the value ".".

To process the pages member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["pages"] does not [=map/exist=], or if |json|["pages"] is not a [=list=], return.
  2. Let |pages| be a new [=list=].
  3. [=list/For each=] |item:string| of |json|["pages"]:
    1. If |item| is not a [=string=], return.
    2. Let |url:URL| be the result of [=URL Parser|parsing=] |item|.
    3. If |url| is failure, [=iteration/continue=].
    4. [=list/Append=] |pages| to |url|.
  4. Set |manifest|["pages"] to |pages|.

platform_version member

The [=MiniApp manifest's=] platform_version member contains a [=MiniApp platform version resource=] [=ordered map=] for describing the minimum requirements and intended platform version to run a MiniApp, including [=MiniApp platform version resource/min_code=], [=MiniApp platform version resource/target_code=], and [=MiniApp platform version resource/release_type=].

To process the platform_version member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["platform_version"] does not [=map/exist=], or if |json|["platform_version"] is not an [=ordered map=], return.
  2. Let |platform_version:ordered map| be a new [=ordered map=].
  3. Process the platform version's min_code member passing |json|["platform_version"] and |platform_version|.
  4. Process the platform version's target_code member passing |json|["platform_version"] and |platform_version|.
  5. Process the platform version's release_type member passing |json|["platform_version"] and |platform_version|.
  6. If |platform_version|["min_code"] does not [=map/exist=], return failure.
  7. Set |manifest|["platform_version"] to |platform_version|.

req_permissions member

The optional [=MiniApp manifest's=] req_permissions member is a [=list=] of [=MiniApp permission resources=] [=ordered map=].

Each [=MiniApp permission resource=] declares a request for using a concrete system feature (e.g., access to device's location, user contacts, sensors, and camera) required for the proper execution of a MiniApp.

To process the req_permissions member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["req_permissions"] does not [=map/exist=], or if |json|["req_permissions"] is not a [=list=], return.
  2. Let |permissions:list| be a new [=list=].
  3. [=list/For each=] |item:ordered map| of |json|["req_permissions"]:
    1. If |item| is not an [=ordered map=], [=iteration/continue=].
    2. Let |permission:ordered map| be an [=ordered map=].
    3. Process the permission resource's name member passing |item| and |permission|.
    4. If |permission|["name"] does not [=map/exist=], [=iteration/continue=].
    5. Process the permission resource's reason member passing |item| and |permission|.
    6. [=list/Append=] |permission| to |permissions|.
  4. Set |manifest|["req_permissions"] to |permissions|.

User agents will ask for the user's consent to protect their privacy during access to these specific features. This information in the [=req_permissions=] member may be used by app stores or hosting platforms to filter MiniApps according to the user's preferences, privacy policy, or device capabilities.

version member

The [=MiniApp manifest's=] version member contains a [=MiniApp version resource=] [=ordered map=] to represent the [=MiniApp version resource/code=] and [=MiniApp version resource/name=].

To process the version member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["version"] does not [=map/exist=], or if |json|["version"] is not [=ordered map=], return.
  2. Let |version:ordered map| be a new [=ordered map=].
  3. Process the version's code member passing |json|["version"] and |version|.
  4. Process the version's name member passing |json|["version"] and |version|.
  5. Set |manifest|["version"] to |version|.

widgets member

The optional [=MiniApp manifest's=] widgets member is a [=list=] of [=MiniApp widget resources=] that are a part of a MiniApp.

A MiniApp Package MAY include MiniApp pages and Widgets concurrently.

A widget, as part of a MiniApp, applies some of the members of the [=MiniApp manifest=], including:

  • [=dir=];
  • [=lang=];
  • [=app_id=];
  • [=MiniApp manifest/name=];
  • [=short_name=];
  • [=icons=];
  • [=version=]

However, a widget also has its exclusive fields as defined in the [=MiniApp widget resource=].

To process the widgets member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["widgets"] does not [=map/exist=], or if |json|["widgets"] is not a [=list=], return.
  2. Let |widgets:list| be a new empty [=list=].
  3. [=list/For each=] |item:ordered map| of |json|["widgets"]:
    1. If |item| is not an [=ordered map=], [=iteration/continue=].
    2. Let |widget:ordered map| be an [=ordered map=].
    3. Process the widget's name member passing |item| and |widget|.
    4. Process the widget's path member passing |item| and |widget|.
    5. Process the widget's min_code member passing |item|, |manifest|, and |widget|.
    6. If |widget|["name"] does not [=map/exist=], or if |item|["path"] does not [=map/exist=], [=iteration/continue=].
    7. [=list/Append=] |widget| to |widgets|.
  4. Set |manifest|["widgets"] to |widgets|.

window member

The optional [=MiniApp manifest's=] window member contains a [=MiniApp window resource=] [=ordered map=] to describe the look and feel of a MiniApp frame, including the styles of the status bar, navigation bar, title, background colors, among other visual configuration elements.

The [=window=] object members inherit the text direction and language configuration from the [=dir=] and [=lang=] members at the root of the [=MiniApp manifest=].

To process the window member, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |json|["window"] does not [=map/exist=], or if |json|["window"] is not an [=ordered map=], return.
  2. Let |window:ordered map| be a new [=ordered map=] «[ "auto_design_width" → false, "background_color" → "#ffffff", "background_text_style" → "dark", "design_width" → 750, "enable_pull_down_refresh" → false, "fullscreen" → "false", "navigation_bar_background_color" → "#000000", "navigation_bar_text_style" → "white", "navigation_bar_title_text" → "default", "on_reach_bottom_distance" → 50, "orientation" → "portrait" ]».
  3. Process the window's auto_design_width member passing |json|["window"] and |window|.
  4. Process a color member passing |json|["window"], |window| and "background_color".
  5. Process the window's background_text_style member passing |json|["window"] and |window|.
  6. Process the window's design_width member passing |json|["window"] and |window|
  7. Process the window's enable_pull_down_refresh member passing |json|["window"] and |window|.
  8. Process the window's fullscreen member passing |json|["window"] and |window|.
  9. Process a color member passing |json|["window"], |window| and "navigation_bar_background_color".
  10. Process the window's navigation_bar_text_style member passing |json|["window"] and |window|.
  11. Process the window's navigation_bar_title_text member passing |json|["window"] and |window|.
  12. Process the window's navigation_style member passing |json|["window"] and |window|.
  13. Process the window's on_reach_bottom_distance member passing |json|["window"] and |window|.
  14. Process the window's orientation member passing |json|["window"] and |window|.
  15. Process the window's auto_design_width member passing |json|["window"] and |window|.
  16. Set |manifest|["window"] to |window|.

Processing the manifest

The MiniApp manifest, as an extension of the [=Application manifest=], provides a supplementary algorithm to be processed at the extension point of the processing a manifest algorithm defined in [[APPMANIFEST]]. Thus, the user agent starts by processing the [=Application manifest=]'s members and, at the extension point, continues with processing the MiniApp manifest members using the following algorithm.

To process a MiniApp manifest at the extension point, given [=ordered map=] |json:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. If |manifest|["name"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  2. If |manifest|["icons"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  3. Let |icons:ordered map| be |manifest|["icons"].
  4. If |icons|["src"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  5. If |manifest|["icons"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  6. Process the app_id member passing |json| and |manifest|.
  7. If |manifest|["app_id"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  8. Process the color_scheme member passing |json| and |manifest|.
  9. Process the description member passing |json| and |manifest|.
  10. Process the device_type member passing |json| and |manifest|.
  11. Process the pages member passing |json| and |manifest|.
  12. If |manifest|["pages"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  13. Process the platform_version member passing |json| and |manifest|.
  14. If |manifest|["platform_version"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  15. Process the req_permissions member passing |json| and |manifest|.
  16. Process the version member passing |json| and |manifest|.
  17. If |manifest|["version"] does not [=map/exist=], [=exception/throw=] a {{TypeError}}.
  18. Process the widgets member passing |json| and |manifest|.
  19. Process the window member passing |json| and |manifest|.

MiniApp platform version resources

A MiniApp platform version resource is an [=ordered map=] that indicates the minimum and target platform versions to be used by the MiniApp.

The following members are defined under the scope of the [=MiniApp manifest=], addressing specific aspects of a [=platform version resource=].

min_code member

The [=MiniApp platform version resource's=] min_code member is a non-negative integer number that indicates the minimum supported version of the MiniApp user agent's platform to ensure the regular operation of a MiniApp.

To process the platform version's min_code member, given [=ordered map=] |json:ordered map| and [=ordered map=] |platform_version:ordered map|:

  1. If |json|["min_code"] does not [=map/exist=], or if |json|["min_code"] is not a number, return failure.
  2. Set |platform_version|["min_code"] to |json|["min_code"].

release_type member

The [=MiniApp platform version resource's=] release_type member is a [=string=] that indicates the release type of the MiniApp user agent's target platform version that is required for running an application.

MiniApp vendors may recommend specific versioning schemes and values for this member (e.g., CanaryN, BetaN, or Release, where N represents a positive integer, such as Beta1).

To process the platform version's release_type member, given [=ordered map=] |json:ordered map| and [=ordered map=] |platform_version:ordered map|:

  1. If |json|["release_type"] does not [=map/exist=], or if |json|["release_type"] is not a [=string=], return.
  2. Set |platform_version|["release_type"] to |json|["release_type"].

target_code member

The [=MiniApp platform version resource's=] target_code member is a non-negative integer number that indicates the target supported version of the MiniApp user agent's platform to ensure the regular operation of a MiniApp.

To process the platform version's target_code member, given [=ordered map=] |json:ordered map| and [=ordered map=] |platform_version:ordered map|:

  1. If |json|["target_code"] does not [=map/exist=], or if |json|["target_code"] is not a number, return.
  2. Set |platform_version|["target_code"] to |json|["target_code"].

MiniApp permission resources

A MiniApp permission resource is an [=ordered map=] that describes a request for using a concrete system feature (e.g., access to device's location, user contacts, sensors, and camera) required for the proper execution of a MiniApp.

The following members are defined under the scope of the [=MiniApp manifest=], addressing specific aspects of a [=permission resource=].

name member

The [=MiniApp permission resource's=] name member is a [=string=] that indicates the name of the feature requested.

To process the permission resource's name member, given [=ordered map=] |json:ordered map| and [=ordered map=] |permission:ordered map|:

  1. If |json|["name"] does not [=map/exist=], or
    if |json|["name"] is not a [=string=], or if |json|["name"] is the empty string, return.
  2. Set |permission|["name"] to |json|["name"].

reason member

The optional [=MiniApp permission resource's=] reason member is a [=string=] that indicates the reason given to request the feature specified in the [MiniApp permission resource/name=] attribute.

To process the permission resource's reason member, given [=ordered map=] |json:ordered map| and [=ordered map=] |permission:ordered map|:

  1. If |json|["reason"] does not [=map/exist=], or
    if |json|["reason"] is not a [=string=], or if |json|["reason"] is the empty string, return.
  2. Set |permission|["reason"] to |json|["reason"].

MiniApp version resources

A MiniApp version resource is an [=ordered map=] that describes the version code and version name of a MiniApp.

The following members are defined under the scope of the [=MiniApp manifest=], addressing specific aspects of a [=version resource=].

code member

The [=MiniApp version resource's=] code member is a non-negative integer number that represents the version of a MiniApp. It is mainly used for enhancing the maintainability and security of MiniApp (e.g., compatibility among incremental versions). The [=code=] member aims at supporting the development and deployment process, and it is not usually displayed to the end-user.

To process the version's code member, given [=ordered map=] |json:ordered map| and [=ordered map=] |version:ordered map|:

  1. If |json|["code"] does not [=map/exist=], or if |json|["code"] is not a number, return failure.
  2. Let |version:number| be a number, initially 1.
  3. If |json|["code"] is greater than 0, then:
    Set |version| to |json|["code"].
  4. Set |version|["code"] to |version|.

name member

The [=MiniApp version resource's=] name member is a [=string=] mainly used for describing information on the version of a MiniApp, playing an essential role in version control, MiniApp application, and platform compatibility. It is usually considered as the version that is shown publicly and displayed to the user.

The RECOMMENDED format for this member is X.Y.Z, where X, Y, and Z are non-negative integer values (e.g., 1.10.0), as specified in Semantic Versioning [[SEMANTIC-VERSIONING]].

To process the version's name member, given [=ordered map=] |json:ordered map| and [=ordered map=] |version:ordered map|:

  1. If |json|["name"] does not [=map/exist=], or if |json|["name"] is not a [=string=], return failure.
  2. Set |version|["name"] to |json|["name"].

MiniApp widget resource members

A MiniApp widget resource is an [=ordered map=] that defines and configures a widget that is part of a MiniApp.

The following members are defined under the scope of the [=MiniApp manifest=], addressing specific aspects of a [=widget resource=].

name member

The [=MiniApp widget resource's=] name member is a [=string=] that indicates the title of a widget.

To process the widget's name member, given [=ordered map=] |json:ordered map| and [=ordered map=] |widget:ordered map|:

  1. If |json|["name"] does not [=map/exist=], or if |json|["name"] is not a [=string=], return.
  2. Set |widget|["name"] to |json|["name"].

path member

The [=MiniApp widget resource's=] path member is a [=relative-url string=] that defines the corresponding [=page route=] of a widget, represented as in the [=pages=] [=list=].

To process the widget's path member, given [=ordered map=] |json:ordered map| and [=ordered map=] |widget:ordered map|:

  1. If |json|["path"] does not [=map/exist=], or if |json|["path"] is not a [=string=], return.
  2. Let |url:URL| be the result of [=URL Parser|parsing=] |json|["path"].
  3. If |url| is failure, return.
  4. Set |widget|["path"] to |url|.

min_code member

The optional [=MiniApp widget resource's=] min_code member is a number that indicates the minimum platform version supported for a MiniApp widget.

Since Widget APIs and MiniApp APIs may differ, the declaration of the minimum version of the platform may be different. Thus, if the widgets member omits [=MiniApp widget resource/min_code=] explicitly, the user agent will consider the same requirement as the specified in the [=MiniApp platform version resource/min_code=] member in the [=platform_version=] object.

To process the widget's min_code member, given [=ordered map=] |json:ordered map|, [=ordered map=] |widget:ordered map| and [=ordered map=] |manifest:ordered map|:

  1. Set |widget|["min_code"] to |manifest|["min_code"].
  2. If |json|["min_code"] does not [=map/exist=], or if |json|["min_code"] is not a [=string=], return.
  3. Set |widget|["min_code"] to |json|["min_code"].

MiniApp window resource members

A MiniApp window resource is an [=ordered map=] that defines and configures the window that contains a MiniApp.

The following members are defined under the scope of the [=MiniApp manifest=], enabling the description of a MiniApp [=window resource=].

auto_design_width member

The auto_design_width member is a [=boolean=] that indicates whether the [=design_width=] of the page is auto-calculated by the user agent. When [=auto_design_width=] is true, the value of [=design_width=] is ignored. In this case, the system's baseline width is automatically determined according to the pixel density of the screen.

Value by default: false.

To process the window's auto_design_width member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["auto_design_width"] does not [=map/exist=], or if |json|["auto_design_width"] is not a [=boolean=], return.
  2. Set |window|["auto_design_width"] to |json|["auto_design_width"].

background_color member

The background_color member is a [=string=] that specifies the background color of the window that contains a MiniApp.

This member supports [=sRGB=] colors, and it is equivalent to the application manifest's background_color.

Value by default: "#ffffff".

When [=processing a MiniApp manifest=], the process a color member algorithm is used to process the window's background_color member, according to the [[APPMANIFEST]] specification.

background_text_style member

The background_text_style member is a [=string=] that specifies the background text style, indicating a light or dark color theme (i.e., "[=background text style values/`light`=]" or "[=background text style values/`dark`=]").

This member supports the values of prefers-color-scheme and MUST contain one of the following background text style values:

"light"
For light style.
"dark" (default)
For dark style.

To process the window's background_text_style member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["background_text_style"] does not [=map/exist=], or
    if |json|["background_text_style"] is not a [=string=], or
    if |json|["background_text_style"] doesn't [=list/contain=] one of the [=background text style values=], return.
  2. Set |window|["background_text_style"] to |json|["background_text_style"].

design_width member

The design_width member is a number that indicates the baseline width of the page design in pixel unit. It is used for visually adjusting the page components.

The value is a non-negative integer and the value by default is 750.

To process the window's design_width member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["design_width"] does not [=map/exist=], or
    if |json|["design_width"] is not a number, or if |json|["design_width"] is less than 0, return.
  2. Set |window|["design_width"] to |json|["design_width"].

enable_pull_down_refresh member

The enable_pull_down_refresh member is a [=boolean=] that specifies if the pull-to-refresh event is enabled during the interaction with the MiniApp.

Value by default: false.

To process the window's enable_pull_down_refresh member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["enable_pull_down_refresh"] does not [=map/exist=],
    or if |json|["enable_pull_down_refresh"] is not a [=boolean=], return.
  2. Set |window|["enable_pull_down_refresh"] to |json|["enable_pull_down_refresh"].

fullscreen member

The fullscreen member is a [=boolean=] that indicates if the MiniApp is shown in full-screen display mode.

When this member takes the true value, it is equivalent to the [=manifest/fullscreen=] value on the application manifest's [=manifest/display=] member. When it takes false as value, it is equivalent to [=display mode/minimal-ui=].

Value by default: false.

To process the window's fullscreen member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["fullscreen"] does not [=map/exist=],
    or if |json|["fullscreen"] is not a [=boolean=], return.
  2. Set |window|["fullscreen"] to |json|["fullscreen"].

navigation_bar_background_color member

The navigation_bar_background_color member is a [=string=] that specifies the color of the background of the navigation bar of a MiniApp.

This member supports [=sRGB=] colors.

Value by default: "#000000".

This member is processed according to the specified in [[APPMANIFEST]].

When [=processing a MiniApp manifest=], the process a color member algorithm is used to process the window's navigation_bar_background_color member, according to the [[APPMANIFEST]] specification.

navigation_bar_text_style member

The navigation_bar_text_style member is a [=string=] that indicates the text color of the navigation bar title (i.e., "[=text style values/`white`=]" or "[=text style values/`black`=]").

This member MUST contain one of the following text style values:

"white" (default)
For white text color.
"black"
For black text color.

To process the window's navigation_bar_text_style member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["navigation_bar_text_style"] does not [=map/exist=], or
    if |json|["navigation_bar_text_style"] is not a [=string=], or
    if |json|["navigation_bar_text_style"] doesn't [=list/contain=] one of the [=text style values=], return.
  2. Set |window|["navigation_bar_text_style"] to |json|["navigation_bar_text_style"].

navigation_bar_title_text member

The navigation_bar_title_text member is a [=string=] that specifies the title of the navigation bar of a MiniApp.

To process the window's navigation_bar_title_text member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["navigation_bar_title_text"] does not [=map/exist=], or
    if |json|["navigation_bar_title_text"] is not a [=string=], return.
  2. Set |window|["navigation_bar_title_text"] to |json|["navigation_bar_title_text"].

navigation_style member

The navigation_style member is a [=string=] that specifies the style of the navigation bar (i.e., "[=navigation style values/`default`=]" or "[=navigation style values/`custom`=]").

This member MUST contain one of the following navigation style values:

"default" (default)
For applying the style by default.
"custom"
For applying a customized navigation bar.

To process the window's navigation_style member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["navigation_style"] does not [=map/exist=], or
    if |json|["navigation_style"] is not a [=string=], or
    if |json|["navigation_style"] doesn't [=list/contain=] one of the [=navigation style values=], return.
  2. Set |window|["navigation_style"] to |json|["navigation_style"].

The capsule button at the right corner is not customizable.

on_reach_bottom_distance member

The on_reach_bottom_distance member is a number that defines the vertical offset from the bottom of the window required to trigger a page pull-up event. Values for this member are non-negative integers expressed in [=pixel unit=].

Value by default: 50.

To process the window's on_reach_bottom_distance member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["on_reach_bottom_distance"] does not [=map/exist=], or
    if |json|["on_reach_bottom_distance"] is not a number, or
    if |json|["on_reach_bottom_distance"] is less than 0, return.
  2. Set |window|["on_reach_bottom_distance"] to |json|["on_reach_bottom_distance"].

orientation member

The orientation member is a [=string=] that specifies the configuration of the screen orientation for the MiniApp.

This member supports the orientation values: "portrait" and "landscape" defined in {{OrientationLockType}} [[SCREEN-ORIENTATION]].

This member is equivalent to the application manifest's [=manifest/orientation=].

Value by default: "portrait".

To process the window's orientation member, given [=ordered map=] |json:ordered map| and [=ordered map=] |window:ordered map|:

  1. If |json|["orientation"] does not [=map/exist=], or
    if |json|["orientation"] is not a [=string=], or
    if |json|["orientation"] doesn't [=list/contain=] one of the [=orientation values=], return.
  2. Set |window|["orientation"] to |json|["orientation"].

Localizable members

A localizable member is a [=manifest=] member whose content may be adapted to specific linguistic, geographical, and cultural aspects. These localizable members share the language tag ([=lang=]) and display direction ([=dir=]) defined at manifest's root.

The following members are [=localizable members=]:

Dependencies

As a crucial part of a MiniApp Package, the manifest.json file describes several important aspects of a MiniApp by referring to the MiniApp Package resources in different file types, such as the page scripts and visual configuration files in the pages directory and the images in the common directory. Details are specified in [[MINIAPP-PACKAGING]].

The regular operation of a MiniApp relies on the proper configuration in the [=manifest=] and the MiniApp Package availability of resources. Such dependency needs to be checked during both the development phase and deployment phase.

Accessibility considerations

This document specifies a set of metadata, enabling developers and publishers to describe and configure the behavior and appearance of MiniApps. Some manifest attributes, like `color_scheme` and the `window` resource members, aim user agents to generate customized user interfaces to enable interaction between the user and the MiniApp.

The [=icons=] member allows developers to describe the visual and iconic representation of a MiniApp in the platform and operating system. Here, the platform should adequately communicate with the platform accessibility services to represent the images, also using the alternative textual descriptions (e.g., [=icon=]'s label, [=MiniApp manifest/name=] and [=short_name=]) to enhance accessibility (i.e., icons in the home screen of the device, listing in app directories, and app configuration).

User agents must ensure that the user interface is perceivable and operable, so they should take special consideration when processing the members that affect the user agent interface and the rendered content, like with the setup of color schemes and themes (i.e., [=color_scheme=], [=MiniApp window resource/background_color=], [=background_text_style=], [=navigation_bar_background_color=], [=navigation_bar_background_color=], [=navigation_bar_text_style=], and [=navigation_style=]) and other configuration settings like [=orientation=], [=fullscreen=], [=enable_pull_down_refresh=], and [=on_reach_bottom_distance=].

The manifest's window member defines the appearance of the MiniApp, including the look and feel of the navigation bar and other features that modify the user agent's native UI, like fullscreen or orientation. User agents must offer intuitive mechanisms to close the apps, reverting the changes that affected the native UI.

User agents interpreting this manifest should help users orient within and control windows and viewports. They should also provide alternative views addressing the different usage scenarios through the advanced use of the `device_type` member and extending the manifest with vendor-specific members to enhance accessibility. Thus, MiniApp user agents and platforms should provide mechanisms for configuring user stylesheets, themes and customize the display and interaction with the application, complying with the applicable specifications and conventions, in particular the [[[UAAG20]]].

Security considerations

The manifest data helps platforms to configure and process applications properly. The information exposed by the document is public, so third-party agents (e.g., app marketplaces and repositories) may use the manifest information to maintain app versions, classify, and list them.

As the manifest is a JSON document and will commonly be encoded using [[UNICODE]], the security considerations described in [[JSON]] and [[UNICODE-SECURITY]] apply. In order to prevent developers from including custom/unrestrained data in a manifest, implementors may use a more strict schema than that defined in JSON Schema to impose their implementation-specific limits on the member names, types, and value ranges (e.g., to guard against memory overflow, or to meet platform-specific limitations).

The integrity of the MiniApp resources, including the manifest, is protected by a cryptographic hash mechanism as part of the whole MiniApp Package, as detailed in [[MINIAPP-PACKAGING]].

A MiniApp contains different file resources organized in directories within a container. Manifest members like icons, pages, and widgets contain paths referring to local resources on the hosting platform. MiniApp user agents MUST guarantee the sandboxed environment, checking the validity of those paths to prevent illegal access out of a MiniApp package.

Developers may access external MiniApp data resources (i.e., not included in the main package) on the hosting platform (e.g., deep-links to other applications and shared storages) or remote HTTP servers. In the former case, the MiniApp user agent should implement all the required mechanisms to guarantee the sandboxed environment on the platform.

The pages member defines the routes of the components of a MiniApp, including a map of pages with a relative path referring to resources stored within the MiniApp container. User agents MUST ignore external URLs or paths that do not correspond to a valid resource in the MiniApp container.

The manifest specifies the features that could be requested during the operation of a MiniApp, involving access to sensors and communication with other devices, both via network connections and via direct connection to the device (e.g., via Bluetooth, NFC, or USB). The declaration does not imply the access and use of the feature. However, user agents MUST implement mechanisms to guarantee the correct usage of services and APIs and address the potential vulnerabilities in each concrete feature.

Privacy considerations

This specification does not directly deal with sensitive data. However, the information defined in a MiniApp manifest helps the platform configure its privacy policies to let a MiniApp manage other devices' hardware, software, and data resources that could affect privacy.

The MiniApp manifest does not motivate collecting, using, or disclosing personal data. However, MiniApp user agents MUST control the access to sensitive device's services and features that could contribute to fingerprinting. User's behavioral patterns in permission management, along with the device's specific constraints (i.e., MiniApps for automotive, IoT, and SmartTVs), could allow users to be fingerprinted. For this reason, MiniApp user agents MUST control the access to the device's resources and preserve the sandboxed environment, protecting the access to sensitive resources, such as device sensors, external software, and personal data, with no disclosure of user's preferences.

Through the manifest's req_permissions member, developers declare the requirements of a MiniApp to access [=powerful features=]. This member allows the platform to understand the restricted resources the MiniApp may request ([=MiniApp permission resource/name=] member), informing the user about the potential consequences and granting (or keeping blocked) access to these resources. Developers SHOULD use the reason member to state the clear and easy-to-understand rationale for requesting these advanced resources.

User agents MUST manage the user's preferences, including the explicit permissions the user shall grant to use [=powerful features=] (e.g., geolocation and device sensors). The user agent MUST implement mechanisms to remind these user's preferences across sessions, enabling users to revoke and grant the permissions at any time. No other information related to the manifest needs to be persisted across sessions.

As in Web applications, MiniApps can be installed using UI dialogs. In the installation process, the user agent SHOULD display clear information about the app (i.e., [=app_id=], [=MiniApp manifest/name=], [=short_name=], [=icons=], [=description=]). This transparent information allows end-users to make a conscious decision before installing it. Based on this metadata, user agents MAY use digital signature methods within the package, as defined in [[[MINIAPP-PACKAGING]]], to verify the app's integrity and maximize users' trust.

User agents SHOULD provide a mechanism to remove an installed MiniApp. It is RECOMMENDED that at the time of removal, the user agent also presents the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.

This specification uses the Augmented Backus-Naur Form (ABNF) as defined in [[!RFC5234]].

The MiniApp Manifest specification depends on the Infra Standard [[INFRA]] to describe algorithms.

JSON Schema

Developers interested in validating the MiniApp manifest document can use the JSON Schema defined at https://w3c.github.io/miniapp-manifest/manifest_schema.json.

Acknowledgements

To include contributors here!

Extensibility

This specification is based on the [=application manifest=] extensibility principle.

Although proprietary extensions are undesirable, they may be included as a manifest extension. In this case, it is RECOMMENDED to use vendor prefixes for the new members.

We encourage implementors to add proprietary extensions to the Extensions Registry. This allows the community to track what extensions vendors and/or the web community have defined and documented.

The following is an example of three hypothetical vendor extensions.

      {
        ...
        "wechat_new_feature": "foo",
        "ali_new_url_system": "http://example.org",
        "coolminiapp_menu_color": "#FA0000"
        ...
      }