|
| 1 | +--- |
| 2 | +title: Action definition JSON schema for Windows Copilot Runtime Action providers |
| 3 | +description: Describes the format of the action definition JSON file format for Windows Copilot Runtime Action providers. |
| 4 | +ms.topic: article |
| 5 | +ms.date: 02/04/2025 |
| 6 | +ms.localizationpriority: medium |
| 7 | +--- |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +# Action definition JSON schema for Windows Copilot Runtime Action providers |
| 12 | + |
| 13 | +This article describes the format of the action definition JSON file format for Windows Copilot Runtime Actions. This file must be included in your project with the **Build Action** set to "Content" and **Copy to Output Directory** set to “Copy if newer”. Specify the package-relative path to the JSON file in your package manifest XML file. For more information, see [Action provider package manifest XML format](action-provider-manifest.md). |
| 14 | + |
| 15 | +## Example action definition JSON file |
| 16 | + |
| 17 | +```json |
| 18 | +"version": 1, |
| 19 | + "actions": [ |
| 20 | + { |
| 21 | + "id": "Contoso.SampleGreeting", |
| 22 | + "description": "Send greeting with Contoso", |
| 23 | + "icon": "ms-resource//...", |
| 24 | + "inputs": [ |
| 25 | + { |
| 26 | + "name": "UserFriendlyName", |
| 27 | + "kind": "Text" |
| 28 | + }, |
| 29 | + { |
| 30 | + "name": "PetName", |
| 31 | + "kind": "Text", |
| 32 | + "required": false |
| 33 | + } |
| 34 | + ], |
| 35 | + "inputCombinations": [ |
| 36 | + { |
| 37 | + "inputs": ["UserFriendlyName"], |
| 38 | + "description": "Greet ${UserFriendlyName.Text}" |
| 39 | + }, |
| 40 | + { |
| 41 | + "inputs": ["UserFriendlyName", "PetName"], |
| 42 | + "description": "Greet ${UserFriendlyName.Text} and their pet ${PetName.Text}" |
| 43 | + } |
| 44 | + ], |
| 45 | + "contentAgeRating": "child", |
| 46 | + "invocation": |
| 47 | + { |
| 48 | + { |
| 49 | + "type": "Uri", |
| 50 | + "uri": "contoso://greetUser?userName=${UserFriendlyName.Text}&petName=${PetName.Text}", |
| 51 | + }, |
| 52 | + "where": [ |
| 53 | + "${UserFriendlyName.Length > 3}" |
| 54 | + ] |
| 55 | + } |
| 56 | + }, |
| 57 | + { |
| 58 | + "id": "Contoso.SampleGetText", |
| 59 | + "description": "Summarize file with Contoso", |
| 60 | + "icon": "ms-resource://...", |
| 61 | + "inputs": [ |
| 62 | + { |
| 63 | + "name": "FileToSummarize", |
| 64 | + "kind": "File" |
| 65 | + } |
| 66 | + ], |
| 67 | + "inputCombinations": [ |
| 68 | + { |
| 69 | + "inputs": ["FileToSummarize"], |
| 70 | + "description": "Summarize ${FileToSummarize.Path}" |
| 71 | + }, |
| 72 | + ], |
| 73 | + "outputs": [ |
| 74 | + { |
| 75 | + "name": "Summary", |
| 76 | + "kind": "Text" |
| 77 | + } |
| 78 | + ], |
| 79 | + "contentAgeRating": "child", |
| 80 | + "invocation": { |
| 81 | + "type": "COM", |
| 82 | + "clsid": "{...}" |
| 83 | + } |
| 84 | + } |
| 85 | + ] |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +## Action definition JSON properties |
| 90 | + |
| 91 | +The tables below describe the properties of the action definition JSON file. |
| 92 | + |
| 93 | +### Document root |
| 94 | + |
| 95 | +| Property | Type | Description | Required | |
| 96 | +|----------|------|-------------|----------| |
| 97 | +| version | string | Schema version. When new functionality added, the version increments by one. | Yes. | |
| 98 | +| actions | Action[] | Defines the actions provided by the app. | Yes. | |
| 99 | + |
| 100 | +### Action |
| 101 | + |
| 102 | +| Property | Type | Description | Required | |
| 103 | +|----------|------|-------------|----------| |
| 104 | +| id | string | Action identifier. Must be unique per app package. This value is not localizable. | Yes | |
| 105 | +| description | string | User-facing description for this action. This value is localizable. | Yes | |
| 106 | +| icon | string | Localizable icon for the action. This value is an *ms-resource* string for an icon deployed with the app. | No | |
| 107 | +| inputs | Inputs[] | List of entities that this action accepts as input. | Yes | |
| 108 | +| inputCombinations | InputCombination[] | Provides descriptions for different combinations of inputs. | Yes | |
| 109 | +| outputs | Output[] | If specified, must be an empty string in the current release. | No | |
| 110 | +| invocation | Invocation | Provides information about how the action is invoked. | Yes | |
| 111 | +| contentAgeRating | string | A field name from the [UserAgeConsentGroup](/uwp/api/windows.system.userageconsentgroup)that specifies the appropriate age rating for the action. The allowed values are "Child", "Minor", "Adult". If no value is specified, the default behavior allows access to all ages. | No | |
| 112 | + |
| 113 | +### Output |
| 114 | + |
| 115 | +| Property | Type | Description | Required | |
| 116 | +|----------|------|-------------|----------| |
| 117 | +| name | string | The variable name of the entity. This value is not localizable. | Yes | |
| 118 | +| kind | string | A field name from the **ActionEntityKind** enumeration specifying the entity type. This value is not localizable. The allowed values are "None", "Document", "File", "Photo", "Text". | Yes | |
| 119 | + |
| 120 | +### InputCombination |
| 121 | + |
| 122 | +| Property | Type | Description | Required | |
| 123 | +|----------|------|-------------|----------| |
| 124 | +| inputs | string[] | A list of Input names for an action invocation. The list may be empty. | Yes | |
| 125 | +| description | string | Description for the action invocation. This value is localizable. | No | |
| 126 | +| where | string[] | One or more conditional statements determining the conditions under which the action applies. | No | |
| 127 | + |
| 128 | +### Invocation |
| 129 | + |
| 130 | +| Property | Type | Description | Required | |
| 131 | +|----------|------|-------------|----------| |
| 132 | +| type | string | The instantiation type for the action. The allowed values are "uri" and "com" | Yes | |
| 133 | +| uri | string | The absolute URI for launching the action. Entity usage can be included within the string. | Yes, for URI instantiated actions. | |
| 134 | +| clsid | string | The class ID for the COM class that implements **IActionProvider**. | Yes, for COM actions | |
| 135 | +| inputData | A list of name/value pairs specifying additional data for URI actions. | No. Only valid for URI actions. | |
| 136 | + |
| 137 | + |
| 138 | +## ActionEntityKind enumeration |
| 139 | + |
| 140 | +The **ActionEntityKind** enumeration specifies the types of entities that are supported by the Windows Copilot Runtime Actions. In the context of a JSON action definition, the entity kinds are string literals that are case-sensitive. |
| 141 | + |
| 142 | +| Entity kind string | Description | |
| 143 | +|-------|------------|-------------| |
| 144 | +| "File" | Includes all file types that are not supported by photo or document entity types. | |
| 145 | +| "Photo" | Image file types. Supported image file extensions are ".jpg", ".jpeg", and ".png" | |
| 146 | +| "Document" | Document file types. Supported document file extensions are ".doc", ".docx", ".pdf", ".txt" | |
| 147 | +| "Text" | Supports strings of text | |
| 148 | + |
| 149 | +## Entity properties |
| 150 | + |
| 151 | +Each entity type supports one or more properties that provide instance data for the entity. Entity property names are case sensitive. |
| 152 | + |
| 153 | +The following example illustrates how entities are referenced in the query string for actions that are launched via URI activation: |
| 154 | + |
| 155 | +`...?param1=${entityName.property1}¶m2=${entityName.property2}` |
| 156 | + |
| 157 | +For information on using entity properties to create conditional sections in the action definition JSON, see [Where clauses](#where-clauses). |
| 158 | + |
| 159 | +### File entity properties |
| 160 | + |
| 161 | +| Property | Type | Description | |
| 162 | +|----------|------|-------------| |
| 163 | +| "FileName" | string | The name of the file. | |
| 164 | +| "Path" | string | The path of the file. | |
| 165 | +| "Extension" | string | The extension of the file. | |
| 166 | + |
| 167 | +### Document entity properties |
| 168 | + |
| 169 | +The *Document* entity supports the same properties as *File*. |
| 170 | + |
| 171 | +### Photo entity properties |
| 172 | + |
| 173 | +The *Photo* entity supports all of the properties of *File* in addition to the following properties. |
| 174 | + |
| 175 | +| Property | Type | Description | |
| 176 | +|----------|------|-------------| |
| 177 | +| "IsTemporaryPath" | boolean | A value specifying whether the photo is stored in a temporary path. For example, this property is true for photos that are stored in memory from a bitmap, not stored permanently in a file. | |
| 178 | + |
| 179 | +### Text entity properties |
| 180 | + |
| 181 | +| Property | Type | Description | |
| 182 | +|----------|------|-------------| |
| 183 | +| "Text" | string | The full text. | |
| 184 | +| "ShortText" | string | A shortened version of the text, suitable for UI display. | |
| 185 | +| "Title" | string | The title of the text. | |
| 186 | +| "Description" | string | A description of the text. | |
| 187 | +| "Length" | double | The length of the text in characters. | |
| 188 | +| "WordCount" | double | The number of words in the text. | |
| 189 | + |
| 190 | +## Where clauses |
| 191 | + |
| 192 | +The action definition JSON format supports *where* clauses that can be used to implement conditional logic, such as specifying that an action should be invoked only when an entity property has a specified value. |
| 193 | + |
| 194 | +The following operators can be used with *where* clauses. |
| 195 | + |
| 196 | +| Operator | Description | |
| 197 | +|----------|-------------| |
| 198 | +| == | Equality | |
| 199 | +| ~= | Case-insensitive equality | |
| 200 | +| != | Inequality | |
| 201 | +| < | Less than | |
| 202 | +| <= | Less than or equal to | |
| 203 | +| > | Greater than | |
| 204 | +| >= | Greater than or equal to | |
| 205 | +| \|\| | Logical OR | |
| 206 | +| && | Logical AND | |
| 207 | + |
| 208 | +*Where* clauses use the following format: |
| 209 | + |
| 210 | +```json |
| 211 | +"where": [ |
| 212 | + "${<property_accessor>} <operator> <value>" |
| 213 | +] |
| 214 | +``` |
| 215 | + |
| 216 | +The following example shows a *where* clause that evaluates to true if a **File** entity has the file extension ".txt". |
| 217 | + |
| 218 | +```json |
| 219 | +"where": [ |
| 220 | + "${File.Extension} ~= \".txt\"" |
| 221 | +] |
| 222 | +``` |
| 223 | + |
| 224 | +Multiple *where* clauses can be combined using the logical AND and logical OR operators. |
| 225 | + |
| 226 | +```json |
| 227 | +where": [ |
| 228 | + "${File.Extension} ~= \".txt\" || ${File.Extension} ~= \".md\"" |
| 229 | +] |
| 230 | +``` |
| 231 | + |
| 232 | +## Related articles |
| 233 | + |
| 234 | + |
0 commit comments