diff --git a/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country-multi.png b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country-multi.png
new file mode 100644
index 0000000000..33c4b6c7ad
Binary files /dev/null and b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country-multi.png differ
diff --git a/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country.png b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country.png
index f0d637fae6..18d4f87b45 100644
Binary files a/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country.png and b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-country.png differ
diff --git a/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-tag-suggestion.png b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-tag-suggestion.png
new file mode 100644
index 0000000000..c2967b2d66
Binary files /dev/null and b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-tag-suggestion.png differ
diff --git a/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-tags-multi-suggestion.png b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-tags-multi-suggestion.png
new file mode 100644
index 0000000000..203b50a8bb
Binary files /dev/null and b/sources/platform/actors/development/actor_definition/input_schema/images/input-schema-tags-multi-suggestion.png differ
diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification.md b/sources/platform/actors/development/actor_definition/input_schema/specification.md
index 146a27daa7..937b3e4ca2 100644
--- a/sources/platform/actors/development/actor_definition/input_schema/specification.md
+++ b/sources/platform/actors/development/actor_definition/input_schema/specification.md
@@ -154,17 +154,18 @@ Most types also support additional properties defining, for example, the UI inpu
String is the most common input field type, and provide a number of editors and validations properties:
-| Property | Value | Required | Description |
-|----------|--------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `editor` | One of:
- `textfield`
- `textarea`
- `javascript`
- `python`
- `select`
- `datepicker`
- `fileupload`
- `hidden` | Yes | Visual editor used for the input field. |
-| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
-| `minLength` | Integer | No | Minimum length of the string. |
-| `maxLength` | Integer | No | Maximum length of the string. |
-| `enum` | [String] | Required if `editor` is `select` | Using this field, you can limit values to the given array of strings. Input will be displayed as select box. |
-| `enumTitles` | [String] | No | Titles for the `enum` keys described. |
-| `nullable` | Boolean | No | Specifies whether `null` is an allowed value. |
-| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `textfield`, `textarea` and `hidden` editors. |
-| `dateType` | One of - `absolute`
- `relative`
- `absoluteOrRelative`
| No | This property, which is only available with `datepicker` editor, specifies what date format should visual editor accept (The JSON editor accepts any string without validation.).
- `absolute` value enables date input in `YYYY-MM-DD` format. To parse returned string regex like this can be used: `^(\d{4})-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`.
- `relative` value enables relative date input in
`{number} {unit}` format.
Supported units are: days, weeks, months, years.
The input is passed to the Actor as plain text (e.g., "3 weeks"). To parse it, regex like this can be used: `^(\d+)\s*(day\|week\|month\|year)s?$`.
- `absoluteOrRelative` value enables both absolute and relative formats and user can switch between them. It's up to Actor author to parse a determine actual used format - regexes above can be used to check whether the returned string match one of them.
Defaults to `absolute`. |
+| Property | Value | Required | Description |
+|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `editor` | One of:
- `textfield`
- `textarea`
- `javascript`
- `python`
- `select`
- `datepicker`
- `fileupload`
- `hidden` | Yes | Visual editor used for the input field. |
+| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
+| `minLength` | Integer | No | Minimum length of the string. |
+| `maxLength` | Integer | No | Maximum length of the string. |
+| `enum` | [String] | Required if `editor` is `select` | Using this field, you can limit values to the given array of strings. Input will be displayed as select box. Values are strictly validated against this list. |
+| `enumSuggestedValues` | [String] | No | Similar to `enum`, but only suggests values in the UI without enforcing validation. Users can select from the dropdown or enter custom value.
Works only with the `select` editor. |
+| `enumTitles` | [String] | No | Displayed titles for the `enum` or `enumSuggestedValues` properties. |
+| `nullable` | Boolean | No | Specifies whether `null` is an allowed value. |
+| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `textfield`, `textarea` and `hidden` editors. |
+| `dateType` | One of - `absolute`
- `relative`
- `absoluteOrRelative`
| No | This property, which is only available with `datepicker` editor, specifies what date format should visual editor accept (The JSON editor accepts any string without validation.).
- `absolute` value enables date input in `YYYY-MM-DD` format. To parse returned string regex like this can be used: `^(\d{4})-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`.
- `relative` value enables relative date input in
`{number} {unit}` format.
Supported units are: days, weeks, months, years.
The input is passed to the Actor as plain text (e.g., "3 weeks"). To parse it, regex like this can be used: `^(\d+)\s*(day\|week\|month\|year)s?$`.
- `absoluteOrRelative` value enables both absolute and relative formats and user can switch between them. It's up to Actor author to parse a determine actual used format - regexes above can be used to check whether the returned string match one of them.
Defaults to `absolute`. |
:::note Regex escape
@@ -172,10 +173,14 @@ When using escape characters `\` for the regular expression in the `pattern` fie
:::
-#### Select
+#### Select editor for strings
-Enables you to provide a list of predefined values for the string, including display titles.
-Here's an example of `countryCode` input field with a country selection:
+The `select` editor for strings allows users to choose a value from a dropdown list.
+You can either only allow users to select from a set of predefined values, or allow them to specify custom values in addition to suggested values.
+
+##### Select from predefined values
+
+When you need to restrict input to a specific set of values, use the `enum` property:
```json
{
@@ -193,6 +198,25 @@ The `select` editor is rendered as drop-down in user interface:
+##### Select with custom input
+
+When you want to suggest values but still allow custom input, use the `enumSuggestedValues` property:
+
+```json
+{
+ "title": "Tag",
+ "type": "string",
+ "description": "Select or enter a custom tag",
+ "editor": "select",
+ "default": "web",
+ "enumSuggestedValues": ["web", "scraping", "automation"],
+ "enumTitles": ["Web", "Scraping", "Automation"]
+}
+```
+
+This creates a select dropdown with suggested values, but users can also enter custom values:
+
+
#### Code editor
@@ -347,10 +371,10 @@ Properties:
| Property | Value | Required | Description |
|------------|-----------------------------------------------------|----------|-------------------------------------------------------------------------------|
-| `type` | One of | Yes | Defines the type of the field — either an integer or a floating-point number. |
+| `type` | One of | Yes | Defines the type of the field — either an integer or a floating-point number. |
| `editor` | One of: | No | Visual editor used for input field. |
| `maximum` | Integer or Number
(based on the `type`) | No | Maximum allowed value. |
-| `minimum` | Integer or Number
(based on the `type`) | No | Minimum allowed value. |
+| `minimum` | Integer or Number
(based on the `type`) | No | Minimum allowed value. |
| `unit` | String | No | Unit displayed next to the field in UI,
for example _second_, _MB_, etc. |
| `nullable` | Boolean | No | Specifies whether null is an allowed value. |
@@ -643,23 +667,57 @@ Editor type `requestListSources` supports input in formats defined by the [sourc
Editor type `globs` maps to the Crawlee's [GlobInput](https://crawlee.dev/api/core#GlobInput) used by the [UrlPatterObject](https://crawlee.dev/api/core#UrlPatternObject).
Editor type `fileupload` enables users to specify a list of files as input. The input is passed to the Actor as an array of strings. The Actor author is responsible for interpreting the strings, including validating file existence and format. This editor simplifies the process for users to upload files to a key-value store of their choice.
-Editor type `select` allows the user to pick items from a select, providing multiple choices. Please check this example of how to define the multiselect field:
+
+#### Select editor for arrays
+
+The `select` editor for arrays allows users to pick multiple items from a dropdown list. This creates a multiselect field in the UI.
+You can either only allow users to select from a set of predefined values, or allow them to specify custom values in addition to suggested values.
+
+To correctly define options for multiselect, you need to define the `items` property and then provide values in `enum`/`enumSuggestedValues` and (optionally) labels in `enumTitles` properties.
+
+##### Select from predefined values
+
+When you need to restrict selections to a specific set of values, use the `enum` property:
+
+```json
+{
+ "title": "Countries",
+ "description": "Select multiple countries",
+ "type": "array",
+ "editor": "select",
+ "items": {
+ "type": "string",
+ "enum": ["us", "de", "fr", "uk", "jp"],
+ "enumTitles": ["United States", "Germany", "France", "United Kingdom", "Japan"]
+ }
+}
+```
+
+This creates a multiselect dropdown where users can only select from the predefined values:
+
+
+
+##### Select with custom input
+
+When you want to suggest values but still allow custom input, use the `enumSuggestedValues` property:
```json
{
- "title": "Multiselect field",
- "description": "My multiselect field",
+ "title": "Tags",
+ "description": "Select or enter custom tags",
"type": "array",
"editor": "select",
"items": {
"type": "string",
- "enum": ["value1", "value2", "value3"],
- "enumTitles": ["Label of value1", "Label of value2", "Label of value3"]
+ "enumSuggestedValues": ["web", "scraping", "automation", "data", "api"],
+ "enumTitles": ["Web", "Scraping", "Automation", "Data", "API"]
}
}
```
-To correctly define options for multiselect, you need to define the `items` property and then provide values and (optionally) labels in `enum` and `enumTitles` properties.
+This creates a multiselect dropdown with suggested values, but users can also enter custom values:
+
+
#### Array items validation
@@ -883,26 +941,26 @@ Rendered input:
#### Single value properties
-| Property | Value | Required | Description |
-|----------------|-----------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------|
-| `type` | `string` | Yes | Specifies the type of input - `string` for single value. |
-| `editor` | One of - `resourcePicker`
- `textfield`
- `hidden`
| No | Visual editor used for
the input field. Defaults to `resourcePicker`. |
-| `resourceType` | One of - `dataset`
- `keyValueStore`
- `requestQueue`
| Yes | Type of Apify Platform resource |
-| `resourcePermissions` | Array of strings; allowed values: | Yes | Permissions requested for the referenced resource. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes.|
-| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
-| `minLength` | Integer | No | Minimum length of the string. |
-| `maxLength` | Integer | No | Maximum length of the string. |
+| Property | Value | Required | Description |
+|-----------------------|-----------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `type` | `string` | Yes | Specifies the type of input - `string` for single value. |
+| `editor` | One of - `resourcePicker`
- `textfield`
- `hidden`
| No | Visual editor used for
the input field. Defaults to `resourcePicker`. |
+| `resourceType` | One of - `dataset`
- `keyValueStore`
- `requestQueue`
| Yes | Type of Apify Platform resource |
+| `resourcePermissions` | Array of strings; allowed values: | Yes | Permissions requested for the referenced resource. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. |
+| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
+| `minLength` | Integer | No | Minimum length of the string. |
+| `maxLength` | Integer | No | Maximum length of the string. |
#### Multiple values properties
-| Property | Value | Required | Description |
-|----------------|-----------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------|
-| `type` | `array` | Yes | Specifies the type of input - `array` for multiple values. |
-| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. |
-| `resourceType` | One of - `dataset`
- `keyValueStore`
- `requestQueue`
| Yes | Type of Apify Platform resource |
-| `resourcePermissions` | Array of strings; allowed values: | Yes | Permissions requested for the referenced resources. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. Applies to each selected resource. |
-| `minItems` | Integer | No | Minimum number of items the array can contain. |
-| `maxItems` | Integer | No | Maximum number of items the array can contain. |
+| Property | Value | Required | Description |
+|-----------------------|-----------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `type` | `array` | Yes | Specifies the type of input - `array` for multiple values. |
+| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. |
+| `resourceType` | One of - `dataset`
- `keyValueStore`
- `requestQueue`
| Yes | Type of Apify Platform resource |
+| `resourcePermissions` | Array of strings; allowed values: | Yes | Permissions requested for the referenced resources. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. Applies to each selected resource. |
+| `minItems` | Integer | No | Minimum number of items the array can contain. |
+| `maxItems` | Integer | No | Maximum number of items the array can contain. |
#### Resource permissions