diff --git a/src/pages/getting-started/changelog/index.md b/src/pages/getting-started/changelog/index.md index 3dc1d94..03027e7 100644 --- a/src/pages/getting-started/changelog/index.md +++ b/src/pages/getting-started/changelog/index.md @@ -41,6 +41,12 @@ twitter: This page contains the release notes and version history for Adobe InDesign APIs. Stay updated with the latest features, improvements, and bug fixes. +## March 18, 2026 + +### Enhancements + +- **API Capability Naming Rules for Custom Scripts:** We have introduced key changes in custom script naming. See [Key Concepts — API Capability Naming Rules][13] for details and examples. + ## February 24, 2026 ### New Features @@ -129,3 +135,4 @@ This page contains the release notes and version history for Adobe InDesign APIs [10]: ../../guides/working-with-datamerge-api/index.md#utf-8-encoded-csv-file-support [11]: ../../api/index.md [12]: ../../guides/pdf-to-indesign-conversion-notes/index.md +[13]: ../concepts/index.md#api-capability-naming-rules diff --git a/src/pages/getting-started/concepts/index.md b/src/pages/getting-started/concepts/index.md index 12b06e7..f5075fa 100644 --- a/src/pages/getting-started/concepts/index.md +++ b/src/pages/getting-started/concepts/index.md @@ -108,8 +108,8 @@ custom-script-folder |File|Description|Required| |---|---|---| -|manifest.json|The custom script manifest. All the details of the script are described in this file.|X| -|script.js|The primary executable for the script. This script gets executed by the product script engine and, depending on the product script engine support, it can depend on other files in nested directories in the ZIP file.|X| +|manifest.json|The custom script manifest. All the details of the script are described in this file.|YES| +|script.js|The primary executable for the script. This script gets executed by the product script engine and, depending on the product script engine support, it can depend on other files in nested directories in the ZIP file.|YES| ### Custom Script manifest @@ -138,29 +138,65 @@ The manifest file is a plain JSON file with the following structure: ``` | Field | Type | Description | Required | -|-------|------|-------------|----------| -| `manifestVersion` | string | The version of the manifest file format. Currently, only 1.0.0 is supported. | X | -| `name` | string | The name of the custom script. The custom script can be invoked using this. It should be between 4-255 characters. It must not have any white space. | X | -| `version` | string | The version number of the custom script, in x.y.z format. The version must be three segments and each version component must be between 0 and 99. | X | -| `host.app` | string | The host application would be used to execute this script. Currently, the only valid value is `indesign`. | X | -| `host.appVersionStrategy` | string | Defines how the system selects the app version for capability execution: latest_version (always uses newest), fixed_major_version (locks to specific major version), or fixed_major_and_minor_version (locks to specific major.minor version). | X | -| `host.majorAppVersion` | string | The major version number of the app (first digit in version format like 20.0.34). When using fixed_major_version strategy, the system automatically selects the latest minor and patch versions within this major version. | X | -| `host.minorAppVersion` | string | The minor version number of the app (second digit in version format like 20.0.34). When using fixed_major_and_minor_version strategy, the system automatically selects the latest patch version within this major.minor combination. | X | -| `apiEntryPoints` | array | An array of `` objects. Describes the API entry points for the custom script. | | +|-------|:----:|-------------|----------| +| `manifestVersion` | string | The version of the manifest file format. Currently, only 1.0.0 is supported. | YES | +| `name` | string| Script name used to invoke the capability. Please refer to [API Capability Naming Rules](#api-capability-naming-rules) for more details. | YES | +| `version` | string| The version number of the custom script, in x.y.z format. The version must be three segments and each version component must be between 0 and 99. | YES | +| `host.app` | string| The host application used to execute this script. Currently, the only valid value is `indesign`. | YES | +| `host.appVersionStrategy` | string| How the system selects the app version: latest_version, fixed_major_version, or fixed_major_and_minor_version. | NO | +| `host.majorAppVersion` | string| The major version of the app (e.g. 20 in 20.0.34). Required when appVersionStrategy is fixed_major_version or fixed_major_and_minor_version. | NO | +| `host.minorAppVersion` | string| The minor version of the app (e.g. 0 in 20.0.34). Required when appVersionStrategy is fixed_major_and_minor_version. | NO | +| `apiEntryPoints` | array | An array of `` objects. Describes the API entry points for the custom script. | NO | - When a customer registers a script without specifying the strategy, the system automatically chooses latest_version as the default strategy. - majorAppVersion parameter is mandatory if appVersionStrategy is fixed_major_version. - majorAppVersion and minorAppVersion are mandatory if appVersionStrategy is fixed_major_and_minor_version. +### API Capability Naming Rules + +The script name is the `name` field in your custom script manifest. It identifies your capability when registering and invoking the script. Names must follow the rules below. Any non-compliant names will not be permitted for registration. + +**Rules** + +- **Length:** 3–255 characters. +- **Allowed characters** (any other character is rejected): + - **Alphanumeric:** a-z, A-Z, 0-9 + - **Hyphen (-), underscore (_), period (.)** + - **Forward slash (/):** Allowed only as a segment separator for hierarchical names (for example, `renditions/jpeg`). Do not use leading or trailing slashes, or consecutive slashes. + +**Valid name examples** + +| Example | Notes | +|--------|--------| +| `my-script` | Lowercase, hyphen and 3+ characters. | +| `export_to_idml` | Underscores allowed. | +| `Rendition.v1` | Period and mixed case allowed. | +| `renditions/jpeg` | Forward slash as segment separator for a hierarchy. | +| `com.acme.scripts/processor` | Combined period and slash. | + +**Names that are rejected** + +| Example | Reason | +|--------|--------| +| `ab` | Too short (fewer than 3 characters). | +| `my script` | Space not allowed. | +| `script@work` | At sign (@) not allowed. | +| `script#2` | Hash (#) not allowed. | +| `renditions//jpeg` | Consecutive slashes not allowed. | +| `/renditions/jpeg` | Leading slash not allowed. | +| `renditions/jpeg/` | Trailing slash not allowed. | +| `café` or `naïve` | Accented characters not allowed. | + + ### The `apiEntryPoints` field In the manifest file, the `apiEntryPoints` attribute is an array of `EntryPointDefinition` objects with the following format: |Field|Type|Description|Required| |---|---|---|---| -|`type`|string|The type of entry point. Valid values are `capability`.|X| -|`path`|string|The file path should be used based on the type. The default is to look for the files in the root directory of the ZIP file. However, this can also be any nested path in the ZIP file.|X| -|`language`|string|The language of the script. It can be an extended script, UXP script, or JavaScript.|| +|`type`|string|The type of entry point. Valid values are `capability`.|YES| +|`path`|string|The file path should be used based on the type. The default is to look for the files in the root directory of the ZIP file. However, this can also be any nested path in the ZIP file.|YES| +|`language`|string|The language of the script. It can be an extended script, UXP script, or JavaScript.|YES| - Each entry point specifies a custom script or a custom script specification. - There can be only one entry of each type in the array. diff --git a/src/pages/guides/working-with-custom-scripts-api/index.md b/src/pages/guides/working-with-custom-scripts-api/index.md index 7e659fc..96fdc8b 100644 --- a/src/pages/guides/working-with-custom-scripts-api/index.md +++ b/src/pages/guides/working-with-custom-scripts-api/index.md @@ -39,6 +39,7 @@ Then use those custom scripts on documents by referencing the `{SCRIPT_ID}` and ## Before you start - You'll need [a valid access token and client ID][2]. +- **Script naming:** The script name (the `name` in your manifest) must be 3–255 characters and should only use: a-z, A-Z, 0-9, hyphen (-), underscore (_), period (.), and forward slash (/) as a segment separator (for example, `renditions/jpeg`). Everything else is rejected. See [Key Concepts — API Capability Naming Rules][7] for details. In the cURL commands, be sure to: @@ -152,3 +153,4 @@ Consult this skeleton [cURL request][6] for more details. [4]: ../../api/ [5]: ../../getting-started/concepts/index.md#Pre-signed-URLs [6]: https://developer.adobe.com/commerce/webapi/get-started/gs-curl/ +[7]: ../../getting-started/concepts/index.md#api-capability-naming-rules diff --git a/src/pages/guides/writing-scripts-for-custom-scripts-api/index.md b/src/pages/guides/writing-scripts-for-custom-scripts-api/index.md index 7b94834..fa2dd09 100644 --- a/src/pages/guides/writing-scripts-for-custom-scripts-api/index.md +++ b/src/pages/guides/writing-scripts-for-custom-scripts-api/index.md @@ -37,6 +37,10 @@ Use this document to construct the script files for the Custom Scripts API. The script's author defines the custom attributes and values for a particular endpoint using *script.js* files in the custom script bundle[1]. Refer to the examples below to construct your scripts. +## Script name requirements + +The script name (the `name` in your manifest) must be 3–255 characters and should only use: a-z, A-Z, 0-9, hyphen (-), underscore (_), period (.), and forward slash (/) as a segment separator (for example, `renditions/jpeg`). Everything else is rejected. See [Key Concepts — API Capability Naming Rules][2] for details. + ## Including input in a custom script ### When no input is required @@ -377,4 +381,5 @@ For comprehensive documentation on all available InDesign Server objects, method [InDesign ExtendScript API Reference (InDesign Server)](https://www.indesignjs.de/extendscriptAPI/indesign-server14/#Application.html) [//]: # (Links) -[1]: ../../getting-started/concepts/index.md#Custom-Script-bundle-structure \ No newline at end of file +[1]: ../../getting-started/concepts/index.md#Custom-Script-bundle-structure +[2]: ../../getting-started/concepts/index.md#api-capability-naming-rules