# Actor input schema specification

Actor input schema is a JSON file which defines the schema and description of the input object and its properties accepted by the Actor on start. The file adheres to [JSON schema](https://json-schema.org/) with our extensions, and describes a single Actor input object and its properties, including documentation, default value, and user interface definition.

The Actor input schema file is used to:

* Validate the passed input JSON object on Actor run, so that Actors don't need to perform input validation and error handling in their code.
* Render user interface for Actors to make it easy for users to run and test them manually.
* Generate Actor API documentation and integration code examples on the web or in CLI, making Actors easy to integrate for users.
* Simplify integration of Actors into automation workflows such as Zapier or Make, by providing smart connectors that smartly pre-populate and link Actor input properties.

To define an input schema for an Actor, set `input` field in the `.actor/actor.json` file to an input schema object (described below), or path to a JSON file containing the input schema object. For backwards compatibility, if the `input` field is omitted, the system looks for an `INPUT_SCHEMA.json` file either in the `.actor` directory or the Actor's top-level directory - but note that this functionality is deprecated and might be removed in the future. The maximum allowed size for the input schema file is 500 kB.

When you provide an input schema, the Apify platform will validate the input data passed to the Actor on start (via the API or Apify Console) to ensure compliance before starting the Actor. If the input object doesn't conform the schema, the caller receives an error and the Actor is not started.

Validation aid

You can use our [visual input schema editor](https://apify.github.io/input-schema-editor-react/) to guide you through the creation of the `INPUT_SCHEMA.json` file.

To ensure the input schema is valid, here's a corresponding [JSON schema file](https://github.com/apify/apify-shared-js/blob/master/packages/json_schemas/schemas/input.schema.json).

You can also use the [apify validate-schema](https://pr-2390.preview.docs.apify.com/cli/docs/reference#apify-validate-schema-path) command in the Apify CLI.

## Example

Imagine a simple web crawler that accepts an array of start URLs and a JavaScript function to execute on each visited page. The input schema for such a crawler could be defined as follows:


```
{
    "title": "Cheerio Crawler input",
    "description": "To update crawler to another site, you need to change startUrls and pageFunction options!",
    "type": "object",
    "schemaVersion": 1,
    "properties": {
        "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "URLs to start with",
            "prefill": [
                { "url": "http://example.com" },
                { "url": "http://example.com/some-path" }
            ],
            "editor": "requestListSources"
        },
        "pageFunction": {
            "title": "Page function",
            "type": "string",
            "description": "Function executed for each request",
            "prefill": "async () => { return $('title').text(); }",
            "editor": "javascript"
        }
    },
    "required": ["startUrls", "pageFunction"]
}
```


The generated input UI will be:

![Apify Actor input schema example](/assets/images/input-schema-example-fa0b2cfdecdbe9dcdb2580759b8d1b12.png)

If you switch the input to the **JSON** display using the toggle, then you will see the entered input stringified to `JSON`, as it will be passed to the Actor:


```
{
    "startUrls": [
    {
        "url": "http://example.com"
    },
    {
        "url": "http://example.com/some-path"
    }
    ],
    "pageFunction": "async () => { return $('title').text(); }"
}
```


## Structure


```
{
    "title": "Cheerio Crawler input",
    "type": "object",
    "schemaVersion": 1,
    "properties": { /* define input fields here */ },
    "required": []
}
```


| Property               | Type    | Required | Description                                                                                                                                    |
| ---------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                | String  | Yes      | Any text describing your input schema.                                                                                                         |
| `description`          | String  | No       | Help text for the input that will be displayed above the UI fields.                                                                            |
| `type`                 | String  | Yes      | This is fixed and must be set to string `object`.                                                                                              |
| `schemaVersion`        | Integer | Yes      | The version of the input schema specification against which your schema is written. Currently, only version `1` is out.                        |
| `properties`           | Object  | Yes      | This is an object mapping each field key to its specification.                                                                                 |
| `required`             | String  | No       | An array of field keys that are required.                                                                                                      |
| `additionalProperties` | Boolean | No       | Controls if properties not listed in `properties` are allowed. Defaults to `true`. Set to `false` to make requests with extra properties fail. |

Input schema differences

Even though the structure of the Actor input schema is similar to JSON schema, there are some differences. We cannot guarantee that JSON schema tooling will work on input schema documents. For a more precise technical understanding of the matter, feel free to browse the code of the [@apify/input_schema](https://github.com/apify/apify-shared-js/tree/master/packages/input_schema/src) package.

## Input fields

Each field of your input is described under its key in the `inputSchema.properties` object. The field might have `integer`, `string`, `array`, `object`, or `boolean` type, and its specification contains the following properties:

| Property             | Value                                                          | Required | Description                                                                                                                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`               | One of - `string` - `array` - `object` - `boolean` - `integer` | Yes      | Allowed type for the input value. Cannot be mixed.                                                                                                                                                                                                                    |
| `title`              | String                                                         | Yes      | Title of the field in UI.                                                                                                                                                                                                                                             |
| `description`        | String                                                         | Yes      | Description of the field that will be displayed as help text in Actor input UI.                                                                                                                                                                                       |
| `default`            | Must match `type` property.                                    | No       | Default value that will be used when no value is provided.                                                                                                                                                                                                            |
| `prefill`            | Must match `type` property.                                    | No       | Value that will be prefilled in the Actor input interface.                                                                                                                                                                                                            |
| `example`            | Must match `type` property.                                    | No       | Sample value of this field for the Actor to be displayed when Actor is published in Apify Store.                                                                                                                                                                      |
| `errorMessage`       | Object                                                         | No       | Custom error messages for validation keywords. See [custom error messages](https://pr-2390.preview.docs.apify.com/platform/actors/development/actor-definition/input-schema/custom-error-messages.md) for more details.                                               |
| `sectionCaption`     | String                                                         | No       | If this property is set, then all fields following this field (this field included) will be separated into a collapsible section with the value set as its caption. The section ends at the last field or the next field which has the `sectionCaption` property set. |
| `sectionDescription` | String                                                         | No       | If the `sectionCaption` property is set, then you can use this property to provide additional description to the section. The description will be visible right under the caption when the section is open.                                                           |

### Prefill vs. default vs. required

Here is a rule of thumb for whether an input field should have a `prefill`, `default`, or be required:

* **Prefill** - Use for fields that don't have a reasonable default. The provided value is prefilled for the user to show them an example of using the field and to make it easy to test the Actor (e.g., search keyword, start URLs). In other words, this field is only used in the user interface but does not affect the Actor functionality and API. Note that if you add a new input option to your Actor, the Prefill value won't be used by existing integrations such as Actor tasks or API calls, but the Default will be if specified. This is useful for keeping backward compatibility when introducing a new flag or feature that you prefer new users to use.
* **Required** - Use for fields that don't have a reasonable default and MUST be entered by the user (e.g., API token, password).
* **Default** - Use for fields that MUST be set for the Actor run to some value, but where you don't need the user to change the default behavior (e.g., max pages to crawl, proxy settings). If the user omits the value when starting the Actor via any means (API, CLI, scheduler, or user interface), the platform automatically passes the Actor this default value.
* **No particular setting** - Use for purely optional fields where it makes no sense to prefill any value (e.g., flags like debug mode or download files).

In summary, you can use each option independently or use a combination of **Prefill + Required** or **Prefill + Default**, but the combination of **Default + Required** doesn't make sense to use.

## Input types

Most types also support additional properties defining, for example, the UI input editor.

### String

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. 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`. |

Regex escape

When using escape characters `\` for the regular expression in the `pattern` field, be sure to escape them to avoid invalid JSON issues. For example, the regular expression `https:\/\/(www\.)?apify\.com\/.+` would become `https:\\/\\/(www\\.)?apify\\.com\\/.+`.

#### Select editor for strings

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:


```
{
    "title": "Country",
    "type": "string",
    "description": "Select your country",
    "editor": "select",
    "default": "us",
    "enum": ["us", "de", "fr"],
    "enumTitles": ["USA", "Germany", "France"]
}
```


The `select` editor is rendered as drop-down in user interface:

![Apify Actor input schema - country input](/assets/images/input-schema-country-139862e35224e1f1458b2ab8f1386b42.png)

##### Select with custom input

When you want to suggest values but still allow custom input, use the `enumSuggestedValues` property:


```
{
    "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:

![Apify Actor input schema - tag input suggestion](/assets/images/input-schema-tag-suggestion-4eeb02caca475587e779598abd027279.png)

#### Code editor

If the input string is code, you can use either `javascript` or `python` editor for syntax highlighting.

For example:


```
{
    "title": "Page function",
    "type": "string",
    "description": "Function executed for each request",
    "editor": "javascript",
    "prefill": "async () => { return $('title').text(); }"
}
```


Rendered input:

![Apify Actor input schema page function](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABmEAAAFSCAMAAAA99ItlAAABRFBMVEX////MzMwQGBsSFx3yWQxswEre3t4ahP/8/P0Uf/8nLDCOjo7+/v3zXhTj4+PT1NT6+vpqbnDExsY/REgdJCecn6CAyWLt7u7q6urb3Nx6foGqrKz1dzcjeJPw8fG4uruWmZqc1YR1eXtwwk+mqav2gkj0aybg4eHO0NGSk5X09PT4nG6+v8Cio6SR0HhSWFv2jln29vaztreBhYdtcnRgZWj+9fDn5+jzZR2GiYtOUlbIycovf5j0cS739/exsrJZXWD95diKjpD1fD80Oj782cf5rYdCSEv+6+H3lmZ7xlxITVH5tJGusLLb8NIih/8xODv7xar//Pn6vqBdYWQ5P0IqMTWkp6hlamzU7crk5eX93s77yrKKzW/X2Nn80rz4pnzs9+av3ZzJ6b2AgoP0+/KUl5mkyNNrpLe9467J3uSz0drdick+AAAWQ0lEQVR42uzBQQEAAAQEMAp4CHT9YwliWwEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAA5ne7UkBHHt315o2FAZw/PG56LIkRE2VegzEEISqJIgvQ7aBKaXgRZF5Ya3soldj3/8j7Dk5x9iyM2fNIDCe301eenq865+TF8v+H9bixi05Q9IfQRle5miZB4wxxirTGHXCCWnAP5A9ImIfShkiXsPlloHjpL7wPOGnjhPwOoYxxiqzR83eJlBSitIzlCIj1YFLdYZO0CkOAmfYAcYYY9X4hEdtKGeDiPu2gAs0drZdAylCXJUJTB1eqXNiGGPsXb590L4ZzlxQmOvr6w1KEZQRImIGl2kgog+S62cTuNBy6Ah4QzhDvlDGGGPn+/BR+2A48/7CNIE01jYi1qGEOiKGpQpTVqBXMGESZPWlXsUEwBhjrMLCkBoizkCybpPUv4GCNcjW9QZMhLgFJfT7gT+C1zpijYhCiAaAJ8REhUOIKyBX8rRVf+7Jo2KOIKBZpYmQdeoLMaLTQixAGfnBc+KB0sg/feKnfgf+wHOCw7Uy0u7o6vATZYwx9q7CmK6SlSsMfEEc08btt1DaDEDpbZA8+D1EG6RGF3MzC46aqPkANmIPpAEd0yCLNvUon/ZuoYMRY24rSzZFrQ0QIX558yljVaWvcqqm+twlGGWOikrk1JZhzwl0djJgjDF2fmE+GM+XK0ysnhPeoqYrUUNtpgvjFjH58Y7CdFF5soBYe9Q2wlwYq1mM6BwKE6MSg8nSSXVTekBSJwS1BcYYY9UW5i5fw/iI+DhM6TzugHy3aW91H+8QdWHukQa2o3FehEISxYgYRdHCWBiyjT63aJPqmuHDbPiIedWuoiHtzKOofixMV9Zo9nMsR4S6MNiat2MkL+aLZD7kxBJIoi+P+XyZjDHGKi6MpxYHe8qHRYcZHXqyBToklmyOrf/Uzw6VWIBW5ISYC5PQ8YISs6dtIoPj0k5AO4M3d/p1YfzDiD7tdPXH2p7+3RQMao6AVyK9hhFODRhjjFVYmJcVIn4FsAiQRks9e7w6DJg8INoqLCs1YkftObswMUgzdSVuTlOFQNytbQ9NhYnVCNKkPUsVJgPpWhbO4M1iJcyc4Li0YYwxVklhMI7j5grJ3AXNGi3ouK/+9E8hp+/DPNG4MDemvbMLE4DUV3M8vPlNU2GeihE9RLxVhfEOyZn/rTCJ46RLLgxjjF3wxuW3E+cvfqc/toBYWfzUwlxfveRyBbm1qoP6mTY+uzADlYtijvbpwtCICHJXcm2lCgO57hmFyW/pAF8lY4yxCh0Ls4ksIDdjJEVhXmgjIBfkdbDwtcezC1MvCqOOsxOFUSPWkJvQbnK6MCcXKwnf6WeMsUpQYXYDUu+4x2+evLtP18lvV8m6xfrjbprrT6dfTxemZiiMnmN4sjDFCNW4gbkw5qeVj/hpZcYYq5C+01/oHJ7Ucm0qjCrO1gUS7hBtw412Q2Fo5DNIU0Nh9Bx7UFzLWBga0YRiDs9cGPMblwV+45IxxqphLsz08OVidVSF6dL2XjZgjKoOM8SHCUgiSW6NhfmC2AVp/ofCzA53d6wV4k9dmKAojBrR8vIRY8QNnFUYzwlAy2RW+FtjGGOsGubCvOj/8PL9SRfmZkM7u+YWJVunZ2vJorQQU2NhZvqlyDWaCqPnuB4BuPfqQTFw1aS6MHrEikZYn1XhzIUxf/MlqdUA+Jsvf7F3Ry8JA3EAx3+7h7Qmm65JLqGgF0WSMIvQB5UR9BBhDxXRQ0/9/39Dd9vFlB2BBLrk+3lQGIf49uW23R0A7IK7MPbmmLpK32NlCyNJrHJpXgdpm9S0JgtTnpGzMHOlvdwcK3dhtKHSFq0j8ymGGRvfXuaFKUa8ZyPqpcKwez8AVN56YWwdjMWrLYx4U6VNw0tbB5koK07EVZhi57KxszBGqqzHjhhPpZ0vixEjKRWGE8gAoPLKyxejB6WlI/3VlVwnDM9Ern/q0Gg/Z32ZnMiq0BZGa14cmRnOdegozJtkhvdKux83JXe+yAvTVupqdUR8eibrhRmXC+M+RTngFGUA2NmKS7fZZ68uPxLPSyQzKc43btz1+52G/ObD+6iLU/Eb4UBWNAeD0oh+r7nhf+/6/jBKgiCJhr7f5RYZAGxr15jNpdmSejuJOJXqC+a+NectMgCocmFOlPb4lT3Yj3vyH8wCL4o88gIAFS+MPMXKej0QAMBe225h5K71bOYv0/FAAAD7bYuFsWa9oCEAgL1XO9QpMZbFW2SGuSwAAPyhMFZt/QqFAQBQGABAFS1r1tJxBQAAAAAAAAAAAAAAAAAAfLN3xyYQw0AQRTW5kWJXIFCm/ps7cAO3ymx4r4nPsMECAAAAAAC8xJojAFAy5mpVMwBwYLaaO+nb7xcASq7dk7u4YMZuAFC2R2nFrERgADiyk1WZML0BwJFeGTHDhAHg1M5ofyWO/AAcupJKYRoAHFIYAB4KA8BHKAwAD4UB4CMUBoCHwgD82K/D1yTiOI7jH/imyDCuy7ytLW3qg5qYYhmjIVYgLBru0YhlODAJrP//D2jeptPo8keczpP369lxDz73g+PeHBKCwgAAQhQGAJAQFAYAEKIwAICEoDAAgBCFAQAkBIUBAIQoDABgg7zcjUZhAAD/L80/DABggsIAABKCwgAAQhQGAJAQFAYAEKIwa5T3e7qRbflXiknxsJHbeaV7dOz7Ta1RzT/SamTKvrd8pLrTPWl5AuCEwqxF2uyxbl1aQ/HInNm1Q62Td6R5LTvRTCkIfirS90FdfzMMJgaKNAiCoW49NVvRW3JgVlw+UrSJKwFwsU2FeTRut8faSBeWuzumWU2x8Mwu09WMlvv07aPikbc/nuC5ZoJUqqSp7Gg0lLRw964qo5GmzlMTFUWqpFLnmmrYWVZRiv09Oer0+5rX3LF9l5HO3nuzsgAst02FqY4L19raRJ7ZgWZO7VSx6Jml5eTZg4exFSa7UM4vmYjCfA0vIgpTmovGj3q9XnEuTO1ffd63nBy9NttdPJe9cBtRwxoC4GB7CvOrUNjcwpTtSWchDF5MX3trrrcwtXc5e/umd6wbfbO8XAtTCgaLhZnz2bkwma59WEFhsl27kNuIWvabnbv9StsK4Dj+8/xiD4cTFHmoVJ1YnpxiEadSH0anoogVdwRn25W22ud1+//f7ya5kGu9KdRxus7dzwsNErzBF/maXJJzGIYxiFtTmL9EXT7+/H0WZpHcgy8aZmZYhYl+y8IsLtMTh2ePnB2oMNIQCoMH5PPhFyZGxjDYIMhwH4ZhDOD2FObPn/8C/mFhDo5qhWq5acNj12uFwkyxA6BSLL6Aa7dYPABaxTpa5UKt6b+2WCvMHDWgs0RuQzHBMPr7MDJwYbwt7NgvyoWZuu0+vMwXasWGfKa4YVlFoQmhXmzBcVm8gOOsWEfjcqaa73i/xVkuN6CxRmYmuDR3HofnkMvQFuZNqfRydPRxSfDicN8l81IqPR4dfVkStIV5W7qbvXs/GlCYO2QOGtFcLrfFcE6QrXg+PbW+lw5BeJXLpeCYz+XuAelcLkMmxarT8KySIQQMEp2enl4yhTGMr3aLCiP808LULM9Gw2tJxPJUgLb4KVxly7pwjwnKliMPV7tsec6gsUqmoFgYaP5kn+fJyS83SCnMgWU1C5ajCKDlbXvEyeKuJcn3ELFqcFhWGY6qFWlZLnfdI++lB7gmRE54M/1jcM2SGW1hRDF63sDhLcNb9ukKUxp1ZX/XFyZKTkAjxZ4dOKblg0kAYwluhQA8ijOcAvbZ02vlPhAwSIpk/EphnsAwjEGYwvhENmbK5YJlRWwIYmEjf1SLOIVB3rI6EOyIteGuKtbKO187gHw8Uxbr1qFxTNpQ/EKe4LrFCcVP2KIwsW0j0DJpK4URByqFmQ3rCGi5m+Ns1C5QyefzEdFCoRhQGPFmqgWvMELVWX0G14yR015hpBiZ1BdGfG5ZRCZ7V3jrPfX4sQhF79PHYvnxXUFTmJeiLndfOq+2tYXBKU+hsbK5uRlnYlOYlgd44dXkM3LLBpD2TlROkTHnuc3NHXJKrLoH1yOZJXWQwMLskfMwDKM/UxjFZdOGcGRZTQAV+S9/u9kGcCD3x2eWVfSKUqgATfnTljzwaZfPoHHKOFTjZBLXpahYhT2SobA/l4LeJHkMpTBWoQGg1YK94R5o4YUMhT8Poy+MZV26Z9O8wpwBbfELrpctSu5cKcwJmYbi/evX0a//LJksjP+yrPNUSbzc/7VQ7JADzMNMJng8682o/CKPI7dlZzTzMA/JVWgG0RbmhJyDYRj9mcJcV/F2vQ3LqsG3YUVsLy0V79sFBLkLL8izSgHIZ1DNkpu4bnFKkYawcrJM4dlSCJ87mZsKMxG7UpgGPE0ng3K77EEKk4ckClOAUHSOfq5ZJ+PHDKnzQPegcdPCyLXeulkJvETmHbnSrzD+gUY0zN/c78cMjzvnyrSFGScfaAbRFya6Ra4vJFMwDOOLTGGuurgs12o1ucd1pjR20XXp/nNfkUkRhZHdKUCION+CkWtQrZCrGNDYwimpuQAjTnI9hZ4DJYhHYivzjg1RvkEK01AKU5aNusA1k4cUEhMxeObIsWEXJivOkbmcWRqtTXK2f2HWyb1NxznDgDcVQ4ZT0BbmR3I6cBD74cOHk1DYyQTJ23sHCsP4Lv3XC9MpWFLe208LkZmL3pFN1e1MS+6xlcK05d49SJjHUN0jFzCw8Tg1l2hOL6yR4XG1MEf+hJLvbJDCQCnMpTwZ+ALXhabXExTW7O5cemzYhRlVRKHzjAz1L8w5e+TqaZIx6AszT+4NOghCO+Tx5gdzDGMYfZjCKCoRd2q/WJSFQcsrTrXd/aRZxTlXhuuFachXBIkzAVWafIrr7DHFLFyTyTjJxAdteshltTB1SAVRm67dAQoTUQtT9wujk+TCk+4ppSWxMPzCZEtddsBfM4z+hUkw/lTK2d2t5XZAYWbJiYEGkS/N2DAMow9TGFVdHgVU/F406k5kinBciIWOWEVTGDkdE2iNXIQiSY70n+kHoul1Csu/RKF1yIRamCakvBNDn74wlZsWBovkFhxj5Orwz5Jl8UW22lU7JGgLc8xjXPFcf5ZMesJDzSB6m6S5u7JhDMAURlGW0+IveoWRHxOrQtZkQ6zS0BUmYkVsBJv+bJeUIaP9CzP+zt0nbs4jyAIZ1RWmKGdRggpTlcW8YWGwznB3v/zbjQvz+2fPRWVr5FKgh+opxlWSh2ph9v2qh0NQRI+ZiJHLykx/Cr41MnAQzC0sfIAvw7A5hDGMAZjCKPJyWrwqC9Obfyl099tCFbrC1OSOGe0KNMbIHBRx7kDDfqhYxD7JnXQUwZKawsjlKjztXj3bkAretue/ujCLMa8w0QS3evvaEAJExWX7gYV5I6/EVC6C+dS73rIEz3vopMkf1Y98Ma5N7rQ/dx+SLUrjxJ9uGSFHNDcR1Q0CCuaafsP4arepMPMfP34Ut74UX5/jRi4tq7qLdl7O9HciRw2g4e6IZWuEprYwDfFMsQ27FalDZ5lx+EbIn9DffnhvDL5BCyOLV6sAlWah2ntvtV27V9Ij2HXrqwtzh4cn9+a4PUE+6L2TNII41/O/1hVGXvXy6T3U4mTv//67WD2aFYmJAr+WsqWAv+W5HVSYn8iplO1l5ZCJpyFgNhd/6iVjCsAEGesdMC7f8fO4kuC7zwYxhTGM78q/W5g/fuj64+Yz/e7l7V5hDizB/VFD+YhWW1sY1Lsr14Pmhrev3JYsiv7GQ+jjhExpC9Nwt9v5UlXemzwa61iuyFcXZp5dazY8cW4hSEm5a0x2tOetelsZSPLxSy82krYw98gkggoTPfXvGjMeJnnufHnqflQ5/gjA4n5vKmaNLkhTTCwGDBKiAN864zAMoz9TGNXBhiVs7HqFaRQsV7UD6cx5QlcY+Vqh0IFOaJ/rV8/xD8U2mdMVxr9PWqHZTUdeFKWXQ/k2jwIL09IVBmPJnX3yyfqSOsP0CgHs+9leYUY/L8zrl9krhXl/NysLg19lfR5/gkZGlkA7D4PUwmm3MJidoCORuQMck/e8bHefxcqHwwRJJZ/JgEFekZxAz2yCz2AYRn+3qTDD0GmeVdDTvjirtxroKX/xyv3KC7myTpocg7THJ48wFIth8nB9CTp2p9m8qECr0mo2cENJhuALxZnB0L3/dP/N2/fQmSUfYFChO0vb8yEM5h1PQ/pBkiTn4Xn0bDlB5mAYxiBMYQYkb1R2U1vcgycU5i8Yktg+yTl8S0naUMTIFXxDD3gewtDJQ5OYfpDfyIxfOGE1BMMwBmIKM5D27lnBsur4ztiTr2LP8S0lif+ZUIJ83nsQG5l/BMMwBmIK8zf7dkwDIBDAUPTYWJCBAVY2HIB/MSRVwI0N75n4Q9OP7kwybhBjucbPrMdxDmCewkwUZtufAcA3CgNABYUBIBQGgBIKA0AoDAAlFAaAUBgASigMAKEwAJRQGABCYQAooTAAhMIAUEJhAAiFAaCEwgAQCgNACYUBIBQGgBIKA0AoDAAlFAaAUBgASigMAKEwAJRQGABCYQAooTAAhMIAUEJhAAiFAaCEwgAQCgNACYUBIBQGgBIKAy97dUACAADAMKh/68NaHLSEQAwDwAnDABDDAHDCMADEMACcMAwAMQwAJwwDQAwDwAnDABDDAHDCMADEMACcMAwAMQwAJwwDQAwDwAnDABDDAHDCMADEMACcMAwAMQwAJwwDQAwDwAnDABDDAHDCMADEMACcMAwAMQwAJwwDQAwDwAnDABDDAHDCMADEMACMvTogAQAAYBjUv/XhLQZawgjDAHCGASDCMACcYQCIMAwAZxgAIgwDwBkGgAjDAHCGASDCMACcYQCIMAwAZxgAIgwDwBkGgAjDAHCGASDCMACcYQCIMAwAZxgAIgwDwBkGgAjDAHCGASDCMACcYQCIMAwAZxgAIgwDwBkGgAjDAHCGASDCMACcYQCIMAwAZxjGXh2QAAAAMAzq3/rwFgMtIUCEYQA4wwAQYRgAzjAARBgGgDMMABGGAeAMA0CEYQA4wwAQYRgAzjAARBgGgDMMABGGAeAMA0CEYQA4wwAQYRgAzjAARBgGgDMMABGGAeAMA0CEYQA4wwAQYRgAzjAARBgGgDMMABGGAeAMA0CEYQA4wwAQYRgAzjAARBgGGHt1QAIAAMAwqH/rw1sMtIRwhgEgwjAAnGEAiDAMAGcYACIMA8AZBoAIwwBwhgEgwjAAnGEAiDAMAGcYACIMA8AZBoAIwwBwhgEgwjAAnGEAiDAMAGcYACIMA8AZBoAIwwBwhgEgwjAAnGEAiDAMAGcYACIMA8AZBoAIwwBwhgEgwjAAnGEAiDAMAGcYACLGXh2cAAjDAACME3SMQPcfUMhbqEEQAndLnGEAKIYBYAjDAFAMA8AQhgGgGAaAIQwDQDEMAEMYBoBiGACGMAwAxTAADPF1mGUYAPrDrDhKwwDQHybjaBsGgP4wO84yAOBpGHkAUH4YpisvAGjIeGvnugDglZU7AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADu9uCABAAAAEDQ/9f9CBUAAAYCwt5ft48TOUMAAAAASUVORK5CYII=)

#### Date picker

Example of date selection using absolute and relative `datepicker` editor:


```
{
    "absoluteDate": {
        "title": "Date",
        "type": "string",
        "description": "Select absolute date in format YYYY-MM-DD",
        "editor": "datepicker",
        "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
    },
    "relativeDate": {
        "title": "Relative date",
        "type": "string",
        "description": "Select relative date in format: {number} {unit}",
        "editor": "datepicker",
        "dateType": "relative",
        "pattern": "^(\\d+)\\s*(day|week|month|year)s?$"
    },
    "anyDate": {
        "title": "Any date",
        "type": "string",
        "description": "Select date in format YYYY-MM-DD or {number} {unit}",
        "editor": "datepicker",
        "dateType": "absoluteOrRelative",
        "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$"
    }
}
```


The `absoluteDate` property renders a date picker that allows selection of a specific date and returns string value in `YYYY-MM-DD` format. Validation is ensured thanks to `pattern` field. In this case the `dateType` property is omitted, as it defaults to `"absolute"`.

![Apify Actor input schema - country input](/assets/images/input-schema-date-absolute-8dc55da08b38b38bcf29b531d7c11e5d.png)

The `relativeDate` property renders an input field that enables the user to choose the relative date and returns the value in `{number} {unit}` format, for example `"2 days"`. The `dateType` parameter is set to `"relative"` to restrict input to relative dates only.

![Apify Actor input schema - country input](/assets/images/input-schema-date-relative-d22597d97577947def822c41950040c3.png)

The `anyDate` property renders a date picker that accepts both absolute and relative dates. The Actor author is responsible for parsing and interpreting the selected date format.

![Apify Actor input schema - country input](/assets/images/input-schema-date-both-7331f7016c1256412af2ccfa05c96aa4.png)

#### Advanced date and time handling

While the `datepicker` editor doesn't support setting time values visually, you can allow users to handle more complex datetime formats and pass them via JSON. The following regex allows users to optionally extend the date with full ISO datetime format or pass `hours` and `minutes` as a relative date:

`"pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])(T[0-2]\\d:[0-5]\\d(:[0-5]\\d)?(\\.\\d+)?Z?)?$|^(\\d+)\\s*(minute|hour|day|week|month|year)s?$"`

When implementing time-based fields, make sure to explain to your users through the description that the time values should be provided in UTC. This helps prevent timezone-related issues.

#### File upload

The `fileupload` editor enables users to specify a file as input. The input is passed to the Actor as a string. It is the Actor author's responsibility to interpret this string, including validating its existence and format.

The editor makes it easier to users to upload the file to a key-value store of their choice.

![Apify Actor input schema - fileupload input](/assets/images/input-schema-fileupload-input-f11ad6ffde04eb7892fd96c5cfc68002.png)

The user provides either a URL or uploads the file to a key-value store (existing or new).

![Apify Actor input schema - fileupload input options](/assets/images/input-schema-fileupload-modal-fe1ec6bbc2752b95f5848b0a03f7e32e.png)

### Boolean type

Example options with group caption:


```
{
    "verboseLog": {
        "title": "Verbose log",
        "type": "boolean",
        "description": "Debug messages will be included in the log.",
        "default": true,
        "groupCaption": "Options",
        "groupDescription": "Various options for this Actor"
    },
    "lightspeed": {
        "title": "Lightspeed",
        "type": "boolean",
        "description": "If checked then actors runs at the
            speed of light.",
        "prefill": true
    }
}
```


Rendered input:

![Apify Actor input schema options](/assets/images/input-schema-options-7eae6d4ce07ec3adc9e10890f952db0f.png)

Properties:

| Property           | Value                          | Required | Description                                                                                   |
| ------------------ | ------------------------------ | -------- | --------------------------------------------------------------------------------------------- |
| `editor`           | One of - `checkbox` - `hidden` | No       | Visual editor used for the input field.                                                       |
| `groupCaption`     | String                         | No       | If you want to group multiple checkboxes together, add this option to the first of the group. |
| `groupDescription` | String                         | No       | Description displayed as help text displayed of group title.                                  |
| `nullable`         | Boolean                        | No       | Specifies whether null is an allowed value.                                                   |

### Numeric types

There are two numeric types supported in the input schema: `integer` and `number`.

* The `integer` type represents whole numbers.
* The `number` type can represent both integers and floating-point numbers.

Example:


```
{
    "title": "Memory",
    "type": "integer",
    "description": "Select memory in megabytes",
    "default": 64,
    "maximum": 1024,
    "unit": "MB"
}
```


Rendered input:

![Apify Actor input schema memory](data:image/png;base64,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)

Properties:

| Property   | Value                                   | Required | Description                                                                   |
| ---------- | --------------------------------------- | -------- | ----------------------------------------------------------------------------- |
| `type`     | One of - `integer` - `number`           | Yes      | Defines the type of the field - either an integer or a floating-point number. |
| `editor`   | One of: - `number` - `hidden`           | 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.                                                        |
| `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.                                   |

### Object type

Example of proxy configuration:


```
{
    "title": "Proxy configuration",
    "type": "object",
    "description": "Select proxies to be used by your crawler.",
    "prefill": { "useApifyProxy": true },
    "editor": "proxy"
}
```


Rendered input:

![Apify Actor input schema proxy](/assets/images/input-schema-proxy-5407b712ef88623fe43dff44904786d1.png)

The object where the proxy configuration is stored has the following structure:


```
{
    // Indicates whether Apify Proxy was selected.
    "useApifyProxy": Boolean,

    // Array of Apify Proxy groups. Is missing or null if
    // Apify Proxy's automatic mode was selected
    // or if proxies are not used.
    "apifyProxyGroups": String[],

    // Array of custom proxy URLs.
    // Is missing or null if custom proxies were not used.
    "proxyUrls": String[],
}
```


Example of a black box object:


```
{
    "title": "User object",
    "type": "object",
    "description": "Enter object representing user",
    "prefill": {
        "name": "John Doe",
        "email": "janedoe@gmail.com"
    },
    "editor": "json"
}
```


Rendered input:

![Apify Actor input schema user object](data:image/png;base64,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)

Properties:

| Property               | Value                                                | Required | Description                                                                                                                                                                                                                |
| ---------------------- | ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `editor`               | One of - `json` - `proxy` - `schemaBased` - `hidden` | Yes      | UI editor used for input.                                                                                                                                                                                                  |
| `maxProperties`        | Integer                                              | No       | Maximum number of properties the object can have.                                                                                                                                                                          |
| `minProperties`        | Integer                                              | No       | Minimum number of properties the object can have.                                                                                                                                                                          |
| `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 `json` and `hidden` editors.                                                                                                               |
| `properties`           | Object                                               | No       | Defines the sub-schema properties for the object used for validation and UI rendering (`schemaBased` editor). See more info below.                                                                                         |
| `additionalProperties` | Boolean                                              | No       | Controls if sub-properties not listed in `properties` are allowed. Defaults to `true`. Set to `false` to make requests with extra properties fail.                                                                         |
| `required`             | String array                                         | No       | An array of sub-properties keys that are required. Note: This applies only if the object field itself is present. If the object field is optional and not included in the input, its required subfields are not validated. |
| `patternKey`           | String                                               | No       | *Deprecated* (see ). Regular expression that will be used to validate the keys of the object.                                                                                                                              |
| `patternValue`         | String                                               | No       | *Deprecated* (see ). Regular expression that will be used to validate the values of object.                                                                                                                                |

#### Object fields validation

Like root-level input schemas, you can define a schema for sub-properties of an object using the `properties` field.

Each sub-property within this sub-schema can define the same fields as those available at the root level of the input schema, except for the fields that apply only at the root level: `sectionCaption` and `sectionDescription`.

Validation is performed both in the UI and during Actor execution via the API. Sub-schema validation works independently of the editor selected for the parent object. It also respects the `additionalProperties` and `required` fields, giving you precise control over whether properties not defined in `properties` are permitted and which properties are mandatory.

Recursive nesting

Object sub-properties can define their own sub-schemas recursively with no nesting depth limit.

Example of an object property with sub-schema properties


```
{
    "title": "Configuration",
    "type": "object",
    "description": "Advanced configuration options",
    "editor": "json",
    "properties": {
        "locale": {
            "title": "Locale",
            "type": "string",
            "description": "Locale identifier.",
            "pattern": "^[a-z]{2,3}-[A-Z]{2}$"
        },
        "timeout": {
            "title": "Timeout",
            "type": "integer",
            "description": "Request timeout in seconds",
            "minimum": 1,
            "maximum": 300
        },
        "debugMode": {
            "title": "Debug Mode",
            "type": "boolean",
            "description": "Enable verbose logging during scraping"
        }
    },
    "required": ["locale", "timeout"],
    "additionalProperties": false
}
```


Rendered input: ![Apify Actor input schema with sub-schema](/assets/images/sub-schema-json-91af0cd8d42e82b8cadabf8bb9f18fb8.png)

In this example, the object has validation rules for its properties:

* The `timeout` property must be an integer between 1 and 300
* The `locale` property must be a string matching the pattern `^[a-z]{2,3}-[A-Z]{2}$`
* The `debugMode` property is optional and can be either `true` or `false`
* The `timeout` and `locale` properties are required
* No additional properties beyond those defined are allowed

##### Handling default and prefill values for object sub-properties

When defining object with sub-properties, it's possible to set `default` and `prefill` values in two ways:

1. *At the parent object level*: You can provide a complete object as the `default` or `prefill` value, which will set values for all sub-properties at once.
2. *At the individual sub-property level*: You can specify `default` or `prefill` values for each sub-property separately within the `properties` definition.

When both methods are used, the values defined at the parent object level take precedence over those defined at the sub-property level. For example, in the input schema like this:


```
{
    "title": "Configuration",
    "type": "object",
    "description": "Advanced configuration options",
    "editor": "schemaBased",
    "default": {
        "timeout": 60
    },
    "properties": {
        "locale": {
            "title": "Locale",
            "type": "string",
            "description": "Locale identifier.",
            "pattern": "^[a-z]{2,3}-[A-Z]{2}$",
            "editor": "textfield",
            "default": "en-US"
        },
        "timeout": {
            "title": "Timeout",
            "type": "integer",
            "description": "Request timeout in seconds",
            "minimum": 1,
            "maximum": 300,
            "editor": "number",
            "default": 120
        }
    }
}
```


The `timeout` sub-property will have a default value of `60` (from the parent object), while the `locale` sub-property will have a default value of `"en-US"` (from its own definition).

#### Schema-based editor

Object with sub-schema defined can use the `schemaBased` editor, which provides a user-friendly interface for editing each property individually. It renders all properties based on their type (and `editor` field), providing a user-friendly interface for complex objects. This feature works for objects (and arrays of objects), enabling each property to have its own input field in the UI.

Objects with a defined sub-schema can use the `schemaBased` editor, which provides a user-friendly interface for editing each property individually. It renders all properties based on their type (and optionally the `editor` field), making it ideal for visually managing complex object structures. This editor supports both single objects and arrays of objects (see ), allowing each property to be represented with an appropriate input field in the UI.

Example of an object property with sub-schema properties using schemaBased editor


```
{
    "title": "Configuration",
    "type": "object",
    "description": "Advanced configuration options",
    "editor": "schemaBased",
    "properties": {
        "locale": {
            "title": "Locale",
            "type": "string",
            "description": "Locale identifier.",
            "pattern": "^[a-z]{2,3}-[A-Z]{2}$",
            "editor": "textfield"
        },
        "timeout": {
            "title": "Timeout",
            "type": "integer",
            "description": "Request timeout in seconds",
            "minimum": 1,
            "maximum": 300,
            "editor": "number"
        },
        "debugMode": {
            "title": "Debug Mode",
            "type": "boolean",
            "description": "Enable verbose logging during scraping",
            "editor": "checkbox"
        }
    },
    "required": ["locale", "timeout"],
    "additionalProperties": false
}
```


Rendered input: ![Apify Actor input schema with sub-schema editor](/assets/images/sub-schema-ui-085aef2f89d03bd16e94159ade1735a5.png)

Each sub-property is rendered with its own input field according to its type and `editor` configuration:

* The `locale` property is rendered as a text field.
* The `timeout` property is rendered as a numeric input with validation limits.
* The `debugMode` property is rendered as a checkbox toggle.

##### Limitations

The `schemaBased` editor supports only **top-level sub-properties** (level 1 nesting). While deeper nested properties can still define sub-schemas for validation, they cannot use the `schemaBased` editor for rendering. For example, if the Configuration object above included a property that was itself an object with its own sub-properties, those deeper levels would need to use a different editor, such as `json`.

### Array

Example of request list sources configuration:


```
{
    "title": "Start URLs",
    "type": "array",
    "description": "URLs to start with",
    "prefill": [{ "url": "https://apify.com" }],
    "editor": "requestListSources"
}
```


Rendered input:

![Apify Actor input schema start urls array](/assets/images/input-schema-start-urls-bef8993a2dd7f9700624e248f733f2e3.png)

Example of an array:


```
{
    "title": "Colors",
    "type": "array",
    "description": "Enter colors you know",
    "prefill": ["Red", "White"],
    "editor": "json"
}
```


Rendered input:

![Apify Actor input schema colors array](data:image/png;base64,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)

Properties:

| Property           | Value                                                                                                                                            | Required | Description                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `editor`           | One of - `json` - `requestListSources` - `pseudoUrls` - `globs` - `keyValue` - `stringList` - `fileupload` - `select` - `schemaBased` - `hidden` | Yes      | UI editor used for input.                                                                                                                                    |
| `placeholderKey`   | String                                                                                                                                           | No       | Placeholder displayed for key field when no value is specified. Works only with `keyValue` editor.                                                           |
| `placeholderValue` | String                                                                                                                                           | No       | Placeholder displayed in value field when no value is provided. Works only with `keyValue` and `stringList` editors.                                         |
| `maxItems`         | Integer                                                                                                                                          | No       | Maximum number of items the array can contain.                                                                                                               |
| `minItems`         | Integer                                                                                                                                          | No       | Minimum number of items the array can contain.                                                                                                               |
| `uniqueItems`      | Boolean                                                                                                                                          | No       | Specifies whether the array should contain only unique values.                                                                                               |
| `nullable`         | Boolean                                                                                                                                          | No       | Specifies whether null is an allowed value.                                                                                                                  |
| `items`            | object                                                                                                                                           | No       | Specifies format of the items of the array, useful mainly for multiselect and for `schemaBased` editor (see below).                                          |
| `isSecret`         | Boolean                                                                                                                                          | No       | Specifies whether the input field will be stored encrypted. Only available with `json` and `hidden` editors.                                                 |
| `patternKey`       | String                                                                                                                                           | No       | *Deprecated* (see ). Regular expression that will be used to validate the keys of items in the array. Works only with `keyValue` editor.                     |
| `patternValue`     | String                                                                                                                                           | No       | *Deprecated* (see ). Regular expression that will be used to validate the values of items in the array. Works only with `keyValue` and `stringList` editors. |

Usage of this field is based on the selected editor:

* `requestListSources` - value from this field can be used as input for the [RequestList](https://crawlee.dev/api/core/class/RequestList) class from Crawlee.
* `pseudoUrls` - is intended to be used with a combination of the [PseudoUrl](https://crawlee.dev/api/core/class/PseudoUrl) class and the [enqueueLinks()](https://crawlee.dev/api/core/function/enqueueLinks) function from Crawlee.

Editor type `requestListSources` supports input in formats defined by the [sources](https://crawlee.dev/api/core/interface/RequestListOptions#sources) property of [RequestListOptions](https://crawlee.dev/api/core/interface/RequestListOptions).

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.

#### 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:


```
{
    "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:

![Apify Actor input schema - multiselect with predefined values](/assets/images/input-schema-country-multi-06939f93e101392f15ef95bc0626c812.png)

##### Select with custom input

When you want to suggest values but still allow custom input, use the `enumSuggestedValues` property:


```
{
    "title": "Tags",
    "description": "Select or enter custom tags",
    "type": "array",
    "editor": "select",
    "items": {
        "type": "string",
        "enumSuggestedValues": ["web", "scraping", "automation", "data", "api"],
        "enumTitles": ["Web", "Scraping", "Automation", "Data", "API"]
    }
}
```


This creates a multiselect dropdown with suggested values, but users can also enter custom values:

![Apify Actor input schema - multiselect with custom values](/assets/images/input-schema-tags-multi-suggestion-cdbf9727cfc9537f5be4c115c967b7dd.png)

#### Array items validation

Arrays in the input schema can define an `items` field to specify the type and validation rules for each item. Each array item is validated according to its `type` and inside the `items` field it's also possible to define additional validation rules such as `pattern`, `minimum`, `maximum`, etc., depending on the item type.

If the item type is an `object`, it can define its own `properties`, `required`, and `additionalProperties` fields, working in the same way as a single object field (see ).

Validation is performed both in the UI and during Actor execution via the API. Array items can themselves be objects with sub-schemas, and objects within objects, recursively, without any limit on nesting depth.

Example of an array of objects property with sub-schema


```
{
    "title": "Request Headers",
    "type": "array",
    "description": "List of custom HTTP headers",
    "editor": "json",
    "items": {
        "type": "object",
        "properties": {
            "name": {
                "title": "Header Name",
                "description": "Name of the HTTP header",
                "type": "string",
                "minLength": 1
            },
            "value": {
                "title": "Header Value",
                "description": "Value of the HTTP header",
                "type": "string",
                "minLength": 1
            }
        },
        "required": ["name", "value"],
        "additionalProperties": false
    },
    "minItems": 1,
    "maxItems": 20
}
```


Rendered input: ![Apify Actor input schema with sub-schema array](/assets/images/sub-schema-array-json-ac43c1fad076eaf2840856a5b46462e0.png)

In this example:

* The array must contain between 1 and 20 items.
* Each item must be an object with `name` and `value` properties.
* Both `name` and `value` are required.
* No additional properties beyond those defined are allowed.
* The validation of each object item works the same as for a single object field (see ).

##### Handling default and prefill values array with object sub-properties

When defining an array of objects with sub-properties, it's possible to set `default` and `prefill` values in two ways:

1. *At the parent array level*: You can provide an array of complete objects as the `default` or `prefill` value, which will be used only if there is no value specified for the field.
2. *At the individual sub-property level*: You can specify `default` or `prefill` values for each sub-property within the `properties` definition of the object items. These values will be applied to each object in the array value.

For example, having an input schema like this:


```
{
    "title": "Requests",
    "type": "array",
    "description": "List of HTTP requests",
    "editor": "schemaBased",
    "default": [
        { "url": "https://apify.com", "port": 80 }
    ],
    "items": {
        "type": "object",
        "properties": {
            "url": {
                "title": "URL",
                "type": "string",
                "description": "Request URL",
                "editor": "textfield"
            },
            "port": {
                "title": "Port",
                "type": "integer",
                "description": "Request port",
                "editor": "number",
                "default": 8080
            }
        },
        "required": ["url", "port"],
        "additionalProperties": false
    }
}
```


If there is no value specified for the field, the array will default to containing one object:


```
[
    { "url": "https://apify.com", "port": 80 }
]
```


However, if the user adds a new item to the array, the `port` sub-property of that new object will default to `8080`, as defined in the sub-property itself.

#### `schemaBased` editor

Arrays can use the `schemaBased` editor to provide a user-friendly interface for editing each item individually. It works for arrays of primitive types (like strings or numbers) as well as arrays of objects, rendering each item according to its type and optional `editor` configuration.

This makes it easy to manage complex arrays in the UI while still enforcing validation rules defined in the items field.

Example of an array of strings property with sub-schema


```
{
    "title": "Start URLs",
    "type": "array",
    "description": "List of URLs for the scraper to visit",
    "editor": "schemaBased",
    "items": {
        "type": "string",
        "pattern": "^https?:\\/\\/(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(?:\\/\\S*)?$"
    },
    "minItems": 1,
    "maxItems": 50,
    "uniqueItems": true
}
```


Rendered input: ![Apify Actor input schema with sub-schema array string](/assets/images/sub-schema-array-string-268b62ea2a270343ab448873958ade84.png)

* Each item is rendered as a text field.
* The array must contain between 1 and 50 items.
* Duplicate values are not allowed.

Example of an array of objects property with sub-schema


```
{
    "title": "Request Headers",
    "type": "array",
    "description": "List of custom HTTP headers",
    "editor": "schemaBased",
    "items": {
        "type": "object",
        "properties": {
            "name": {
                "title": "Header Name",
                "description": "Name of the HTTP header",
                "type": "string",
                "minLength": 1,
                "editor": "textfield"
            },
            "value": {
                "title": "Header Value",
                "description": "Value of the HTTP header",
                "type": "string",
                "minLength": 1,
                "editor": "textfield"
            }
        },
        "required": ["name", "value"],
        "additionalProperties": false
    },
    "minItems": 1,
    "maxItems": 20
}
```


Rendered input: ![Apify Actor input schema with sub-schema array object](/assets/images/sub-schema-array-object-915f0b98cacb4a2518251f611da6d4a6.png)

* Each array item is represented as a group of input fields (`name` and `value`).
* Validation ensures all required sub-properties are filled and no extra properties are allowed.
* New items can be added up to the `maxItems` limit, and each item is validated individually.

##### Limitations

As with objects, the sub-schema feature for arrays only works for level 1 sub-properties. While the objects in the array can have properties with their own schema definitions, those properties cannot themselves use the `schemaBased` editor.

### Resource type

Resource type identifies what kind of Apify Platform object is referred to in the input field. For example, the Key-value store resource type can be referred to using a string ID. Currently, it supports storage resources only, allowing the reference of a Dataset, Key-Value Store or Request Queue.

For Actor developers, the resource input value is a string representing either the resource ID or (unique) name. The type of the property is either `string` or `array`. In case of `array` (for multiple resources) the return value is an array of IDs or names. In the user interface, a picker (`resourcePicker` editor) is provided for easy selection, where users can search and choose from their own resources or those they have access to.

Example of a Dataset input:


```
{
    "title": "Dataset",
    "type": "string",
    "description": "Select a dataset",
    "resourceType": "dataset"
}
```


Rendered input:

![Apify Actor input schema dataset](/assets/images/input-schema-dataset-2c784c5238066c743fd2c4fb28d34fed.png)

The returned value is resource reference, in this example it's the dataset ID as can be seen in the JSON tab:

![Apify Actor input schema dataset](/assets/images/input-schema-dataset-json-1b7772d96d7ddb0a8be8604841754274.png)

Example of multiple datasets input:


```
{
    "title": "Datasets",
    "type": "array",
    "description": "Select multiple datasets",
    "resourceType": "dataset",
    "resourcePermissions": ["READ"]
}
```


Rendered input:

![Apify Actor input schema datasets](/assets/images/input-schema-datasets-40376f5fbddb49389c41f2d34699de26.png)

#### 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: - `READ` - `WRITE`  | 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 - `resourcePicker` - `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: - `READ` - `WRITE`  | 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

If your Actor runs with limited permissions, it must declare what access it needs to resources supplied via input. The `resourcePermissions` field defines which operations your Actor can perform on user-selected storages. This field is evaluated at run start and expands the Actor's [limited permissions](https://pr-2390.preview.docs.apify.com/platform/actors/development/permissions.md) scope to access resources sent via input.

* `["READ"]` - The Actor can read from the referenced resources.
* `["READ", "WRITE"]` - The Actor can read from and write to the referenced resources.

Runtime behavior

This setting defines runtime access only and doesn't change field visibility or whether the field is required in the UI. For array fields (`type: array`), the same permissions apply to each selected resource. Your Actor's run will fail with an insufficient-permissions error if it attempts an operation without the required permission, such as writing with read-only access. Users can see the required permissions in the [input field's tooltip](https://pr-2390.preview.docs.apify.com/platform/actors/running/permissions.md#recognizing-permission-levels-in-console-and-store).

### Deprecation of `patternKey` and `patternValue`

Deprecation notice

**The following properties are deprecated and will only be supported until June 30, 2026:**

* `patternKey` - Used to validate keys in objects and arrays
* `patternValue` - Used to validate values in objects and arrays

These properties are being deprecated to better align with the JSON schema specification. By moving to standard JSON schema, a more consistent experience is provided that matches industry standards while enabling more powerful validation capabilities through the ability to define sub-properties.

#### Alternatives for arrays

For arrays, you can replace `patternKey` and `patternValue` by using the `items` property with a subschema.

Example of replacing `patternValue` for an array of strings:

Old approach with patternValue


```
{
    "title": "Tags",
    "type": "array",
    "description": "Enter tags",
    "editor": "stringList",
    "patternValue": "^[a-zA-Z0-9-_]+$"
}
```


New approach with items subschema


```
{
    "title": "Tags",
    "type": "array",
    "description": "Enter tags",
    "editor": "stringList",
    "items": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9-_]+$"
    }
}
```


Example of replacing both `patternKey` and `patternValue` for an array with key-value pairs:

Old approach with patternKey and patternValue


```
{
    "title": "Headers",
    "type": "array",
    "description": "HTTP headers",
    "editor": "keyValue",
    "patternKey": "^[a-zA-Z0-9-]+$",
    "patternValue": "^.+$"
}
```


New approach with items subschema


```
{
    "title": "Headers",
    "type": "array",
    "description": "HTTP headers",
    "editor": "keyValue",
    "items": {
        "type": "object",
        "properties": {
            "key": {
                "title": "Name",
                "type": "string",
                "description": "Header name",
                "pattern": "^[a-zA-Z0-9-]+$"
            },
            "value": {
                "title": "Value",
                "type": "string",
                "description": "Header value",
                "pattern": "^.+$"
            }
        },
        "required": ["key", "value"]
    }
}
```


#### Alternatives for objects

For objects, there is currently no direct replacement for `patternKey` and `patternValue` properties. These validation features will not be supported in future versions.

If you need to validate object properties, consider using a predefined schema with the `properties` field instead of allowing arbitrary properties with validation patterns.