1# Declaring Permissions
2
3To request permissions for your application, declare all the permissions one by one in the project configuration file.
4
5## Declaring Permissions in the Configuration File
6
7Declare the permissions required by your application under **requestPermissions** in the **module.json5** file.
8
9| Field| Description| Data Type| Value Range|
10| -------- | -------- | -------- | -------- |
11| name | Name of the permission to request.| String| This field is mandatory. The value must be a permission defined in the system. For details, see [Application Permissions](app-permissions.md).|
12| reason | Reason for requesting the permission.| String| This field is optional. It is used for application release verification. It must be specified for a user_grant permission and support multilingual adaptation.<br>It can be referenced as a string resource in $string: \*\*\* format.<br>For details, see [Specifications for reason](#specifications-for-reason).|
13| usedScene | Use case of the permission. This field is used for application release verification. It has two parameters:<br>- **abilities**: names of the abilities (UIAbility or ExtensionAbility) that use the permission.<br>- **when**: when the permission is used.| Object| **usedScene** is mandatory, where:<br>- **abilities** is optional. The value is a string array of multiple UIAbility or ExtensionAbility names<br>- **when** is optional. Set it to **inuse** or **always** for a user_grant permission. It cannot be empty when set.<br>  |
14
15> **NOTE**<br>
16> The permissions requested for a module are valid in the entire application. You do not need to request the same permissions for the project.
17
18## Example
19
20> **NOTE**
21>
22> The values **ohos.permission.PERMISSION1** and **ohos.permission.PERMISSION2** are only examples and do not exist. Set permissions to match your case.
23
24```json
25{
26  "module" : {
27    // ...
28    "requestPermissions":[
29      {
30        "name" : "ohos.permission.PERMISSION1",
31        "reason": "$string:reason",
32        "usedScene": {
33          "abilities": [
34            "FormAbility"
35          ],
36          "when":"inuse"
37        }
38      },
39      {
40        "name" : "ohos.permission.PERMISSION2",
41        "reason": "$string:reason",
42        "usedScene": {
43          "abilities": [
44            "FormAbility"
45          ],
46          "when":"always"
47        }
48      }
49    ]
50  }
51}
52```
53
54## Specifications for reason
55
56The **reason** field (reason for requesting the permission) is mandatory when a user_grant permission is requested. You must declare each required permission in the application's configuration file.
57
58In the dialog box displayed for the user to grant the permission, the [permission group](app-permission-mgmt-overview.md#permission-groups-and-permissions) is displayed. For details about permission groups, see [Application Permission Groups](app-permission-group-list.md).
59
60### Specifications and Suggestions for the reason Field
61<!--RP1-->
621. Keep the sentence concise without redundant separators.
63
64   **Recommended sentence pattern**: Used for something/Used to do something/Used for doing something.
65
66   **Example**: Used for code scanning and photographing.
67
682. To facilitate multilingual adaptation, keep **reason** under 72 characters (36 Chinese characters displayed in two lines on the UI). It cannot exceed 256 characters.
69
703. If **reason** is not set, the default reason will be used.
71<!--RP1End-->
72### Presentation of reason
73
74The reason for requesting a permission can be presented in two modes: authorization pop-up window and permission details page of an application in **Settings** > **Privacy** > **Permission manager**.
75
761. For the permissions in the **Phone**, **Messaging**, **Calendar**, **Contacts**, and **Call logs** permission groups, the content and usage of each permission requested must be presented to the user.
77
78   **Sentence pattern**: Permissions A, used to/for ... Permission B, used to/for ...
79
80   **Example**: Permission A, used to obtain the call status and mobile network information. Permission B, used for secure operation and statistics charging services.
81
822. For the permissions in other permission groups, only the reason for the first requested permission is presented to the user. The permissions are sorted as they appear in the permission groups under **Permission manager**.
83
84   **Example**: If a permission group consists of permissions A, B, and C in sequence, and permissions C and B are requested, the reason for using permission B is presented to the user.
85