module.json5 Configuration File

Configuration File Example

This topic gives an overview of the module.json5 configuration file. To start with, let's go through an example of what this file contains.

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "virtualMachine": "ark",
    "metadata": [
      {
        "name": "string",
        "value": "string",
        "resource": "$profile:distributionFilter_config"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when": "inuse"
        }
      }
    ],
    "targetModuleName": "feature",
    "targetPriority": 50
  }
}

Tags in the Configuration File

As shown above, the module.json5 file contains several tags.

Table 1 Tags in the module.json5 file

deviceTypes

Table 2 deviceTypes

Example of the deviceTypes structure:

{
  "module": {
    "name": "myHapName",
    "type": "feature",
    "deviceTypes" : [
       "tablet"
    ]
  }
}

pages

The pages tag is a profile that represents information about specified pages.

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // Configured through the resource file in the profile
  }
}

Define the main_pages.json file under resources/base/profile in the development view. The file name (main_pages in this example) can be customized, but must be consistent with the information specified by the pages tag. The file lists the page information of the current application, including the route information and the window-related configuration.

Table 3 pages

Table 4 window

{
  "src": [
    "pages/index/mainPage",
    "pages/second/payment",
    "pages/third/shopping_cart",
    "pages/four/owner"
  ],
  "window": {
    "designWidth": 720,
    "autoDesignWidth": false
  }
}

metadata

The metadata tag represents the custom metadata of the HAP. The tag value is an array and contains three subtags: name, value, and resource.

Table 5 metadata

The value of resource is in the format of $profile:file name, where $profile indicates that the resource is placed under /resources/base/profile in the project directory. For example, $profile:shortcuts_config indicates the /resources/base/profile/shortcuts_config.json file.

{
  "module": {
    "metadata": [{
      "name": "module_metadata",
      "value": "a test demo for module metadata",
      "resource": "$profile:shortcuts_config"
    }],

    "abilities": [{
      "metadata": [{
        "name": "ability_metadata",
        "value": "a test demo for ability",
        "resource": "$profile:config_file"
      },
      {
        "name": "ability_metadata_2",
        "value": "a string test",
        "resource": "$profile:config_file"
      }],
    }],

    "extensionAbilities": [{
      "metadata": [{
        "name": "extensionAbility_metadata",
        "value": "a test for extensionAbility",
        "resource": "$profile:config_file"
      },
      {
        "name": "extensionAbility_metadata_2",
        "value": "a string test",
        "resource": "$profile:config_file"
      }],
    }]
  }
}

abilities

The abilities tag represents the UIAbility configuration of the module, which is valid only for the current UIAbility component.

Table 6 abilities

Example of the abilities structure:

{
  "abilities": [{
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ts",
    "launchType":"singleton",
    "description": "$string:description_main_ability",
    "icon": "$media:icon",
    "label": "Login",
    "permissions": [],
    "metadata": [],
    "exported": true,
    "continuable": true,
    "skills": [{
      "actions": ["ohos.want.action.home"],
      "entities": ["entity.system.home"],
      "uris": []
    }],
    "backgroundModes": [
      "dataTransfer",
      "audioPlayback",
      "audioRecording",
      "location",
      "bluetoothInteraction",
      "multiDeviceConnection",
      "wifiInteraction",
      "voip",
      "taskKeeping"
    ],
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:red",
    "removeMissionAfterTerminate": true,
    "orientation": " ",
    "supportWindowMode": ["fullscreen", "split", "floating"],
    "maxWindowRatio": 3.5,
    "minWindowRatio": 0.5,
    "maxWindowWidth": 2560,
    "minWindowWidth": 1400,
    "maxWindowHeight": 300,
    "minWindowHeight": 200,
    "excludeFromMissions": false,
    "unclearableMission": false
  }]
}

skills

The skills tag represents the feature set of wants that can be received by the UIAbility or ExtensionAbility component.

Table 7 skills

Table 8 uris

Example of the skills structure:

{
  "abilities": [
    {
      "skills": [
        {
          "actions": [
            "ohos.want.action.home"
          ],
          "entities": [
            "entity.system.home"
          ],
          "uris": [
            {
              "scheme":"http",
              "host":"example.com",
              "port":"80",
              "path":"path",
              "type": "text/*"
            }
          ]
        }
      ]
    }
  ]
}

extensionAbilities

The extensionAbilities tag represents the configuration of ExtensionAbilities, which is valid only for the current ExtensionAbility.

Table 9 extensionAbilities

Example of the extensionAbilities structure:

{
  "extensionAbilities": [
    {
      "name": "FormName",
      "srcEntry": "./form/MyForm.ts",
      "icon": "$media:icon",
      "label" : "$string:extension_name",
      "description": "$string:form_description",
      "type": "form",
      "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
      "readPermission": "",
      "writePermission": "",
      "exported": true,
      "uri":"scheme://authority/path/query",
      "skills": [{
        "actions": [],
        "entities": [],
        "uris": []
      }],
      "metadata": [
        {
          "name": "ohos.extension.form",
          "resource": "$profile:form_config",
        }
      ]
    }
  ]
}

requestPermissions

The requestPermissions tag represents a set of permissions that the application needs to request from the system for running correctly. For details about how to request permissions, see Applying for Permissions.

NOTE

• The permission settings configured in the requestPermissions tag apply to the entire application.
• If your application needs to subscribe to an event published by itself and the permissions required for accessing the application are set in the permissions tag under extensionAbilities, then the application must register the related permissions in the requestPermissions tag to receive the event.

Table 10 requestPermissions

Example of the requestPermissions structure:

{
  "module" : {
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "EntryFormAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

shortcuts

The shortcuts tag provides the shortcut information of an application. The value is an array and consists of four sub-attributes: shortcutId, label, icon, and wants.

The shortcut information is identified in metadata, where:

• name indicates the name of the shortcut, identified by ohos.ability.shortcuts.

• resource indicates where the resources of the shortcut are stored.

Table 11 shortcuts

1. Configure the shortcuts_config.json file in /resources/base/profile/.

   {
     "shortcuts": [
       {
         "shortcutId": "id_test1",
         "label": "$string:shortcut",
         "icon": "$media:aa_icon",
         "wants": [
           {
             "bundleName": "com.ohos.hello",
             "moduleName": "entry",
             "abilityName": "EntryAbility"
           }
         ]
       }
     ]
   }
   

2. In the abilities tag of the module.json5 file, configure the metadata tag for the UIAbility component to which a shortcut needs to be added so that the shortcut configuration file takes effect for the UIAbility.

   {
     "module": {
       // ...
       "abilities": [
         {
           "name": "EntryAbility",
           "srcEntry": "./ets/entryability/EntryAbility.ts",
           // ...
           "skills": [
             {
               "entities": [
                 "entity.system.home"
               ],
               "actions": [
                 "ohos.want.action.home"
               ]
             }
           ],
           "metadata": [
             {
               "name": "ohos.ability.shortcuts",
               "resource": "$profile:shortcuts_config"
             }
           ]
         }
       ]
     }
   }
   

distributionFilter

The distributionFilter tag defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when the application market distributes applications.

NOTE

This tag is supported since API version 10. In earlier versions, the distroFilter tag is used.

• Application scenario:

  If a project has multiple entry-type modules and the values of deviceType configured for these modules overlap, you need to use this tag to distinguish the modules. In the following example, both entry-type modules support the tablet type, and therefore the distributionFilter tag is required.

  // Device types supported by entry1
  {
    "module": {
      "name": "entry1",
      "type": "entry",
      "deviceTypes" : [
        "tv",
        "tablet"
      ]
    }
  }
  

  // Device types supported by entry2
  {
    "module": {
      "name": "entry2",
      "type": "entry",
      "deviceTypes" : [
        "car",
        "tablet"
      ]
    }
  }
  

• Configuration rules:

  This tag consists of four attributes: screenShape, screenWindow, screenDensity, and countryCode.

  During distribution, a unique HAP is determined based on the mapping between deviceTypes and the preceding attributes.

  • When configuring this tag, include at least one of the attributes.
  • If any one or more attributes are set for one entry-type module, the same attributes must be set for all other entry-type modules.
  • The screenShape and screenWindow attributes are available only for lite wearables.

• Configuration:

  This tag must be configured in the /resources/base/profile directory and be referenced in the resource field of metadata.

Table 12 distributionFilter

screenShape

Table 13 screenShape

screenWindow

Table 14 screenWindow

screenDensity

Table 15 screenDensity

countryCode

Table 16 countryCode

Example:

1. Configure the distributionFilter_config.json file (this file name is customizable) in resources/base/profile under the development view.

   {
     "distributionFilter": {
       "screenShape": {
         "policy": "include",
         "value": [
           "circle",
           "rect"
         ]
       },
       "screenWindow": {
         "policy": "include",
         "value": [
           "454*454",
           "466*466"
         ]
       },
       "screenDensity": {
         "policy": "exclude",
         "value": [
           "ldpi",
           "xldpi"
         ]
       },
       "countryCode": {// Distribution in China is supported.
         "policy": "include",
         "value": [
           "CN"
         ]
       }
     }
   }
   

2. Configure metadata in the module tag in the module.json5 file.

   {
     "module": {
       // ...
       "metadata": [
         {
           "name": "ohos.module.distribution",
           "resource": "$profile:distributionFilter_config",
         }
       ]
     }
   }
   

testRunner

The testRunner tag represents the supported test runner.

Table 17 testRunner

Example of the testRunner structure:

{
  "module": {
    // ...
    "testRunner": {
      "name": "myTestRunnerName",
      "srcPath": "etc/test/TestRunner.ts"
    }
  }
}

atomicService

The atomicService tag represents the atomic service configuration. It is available only when bundleType is set to atomicService in the app.json file.

Table 18 atomicService

Table 19 preloads

Example of the atomicService structure:

{
  "module": {
    "atomicService": {
      "preloads":[
        {
          "moduleName":"feature"
        }
      ]
    }
  }
}

dependencies

The dependencies tag identifies the list of shared libraries that the module depends on when it is running.

Table 20 dependencies

Example of the dependencies structure:

{
  "module": {
    "dependencies": [
      {
        "bundleName":"com.share.library",
        "moduleName": "library",
        "versionCode": 10001
      }
    ]
  }
}

proxyData

The proxyDatas tag provides the list of data proxies provided by the module. It can be configured only for entry and feature modules.

Table 21 proxyData

Example of the proxyData structure:

{
  "module": {
    "proxyData": [
      {
        "uri":"datashareproxy://com.ohos.datashare/event/Meeting",
        "requiredReadPermission": "ohos.permission.GET_BUNDLE_INFO",
        "requiredWritePermission": "ohos.permission.GET_BUNDLE_INFO",
        "metadata": {
          "name": "datashare_metadata",
          "resource": "$profile:datashare"
        }
      }
    ]
  }
}