diff --git a/sources/academy/platform/deploying_your_code/input_schema.md b/sources/academy/platform/deploying_your_code/input_schema.md index 042273af8c..b2d2c708b2 100644 --- a/sources/academy/platform/deploying_your_code/input_schema.md +++ b/sources/academy/platform/deploying_your_code/input_schema.md @@ -61,7 +61,7 @@ Each property's key corresponds to the name we're expecting within our code, whi ## Property types & editor types {#property-types} -Within our new **numbers** property, there are two more fields we must specify. Firstly, we must let the platform know that we're expecting an array of numbers with the **type** field. Then, we should also instruct Apify on which UI component to render for this input property. In our case, we have an array of numbers, which means we should use the **json** editor type that we discovered in the ["array" section](/actors/development/actor-definition/input-schema/specification/v1#array) of the input schema documentation. We could also use **stringList**, but then we'd have to parse out the numbers from the strings. +Within our new **numbers** property, there are two more fields we must specify. First, we must let the platform know that we're expecting an array of numbers with the **type** field. Then, we should also instruct Apify on which UI component to render for this input property. In our case, we have an array of numbers, which means we should use the **json** editor type that we discovered in the ["array" section](/actors/development/actor-definition/input-schema/specification/v1/array) of the input schema documentation. We could also use **stringList**, but then we'd have to parse out the numbers from the strings. ```json { diff --git a/sources/academy/platform/getting_started/inputs_outputs.md b/sources/academy/platform/getting_started/inputs_outputs.md index 08998b1b58..dbe6132277 100644 --- a/sources/academy/platform/getting_started/inputs_outputs.md +++ b/sources/academy/platform/getting_started/inputs_outputs.md @@ -69,7 +69,7 @@ This step isn't necessary, as the Actor will still be able to take input in JSON :::tip Learn more -If you're interested in learning more about how the code works, and what the `INPUT_SCHEMA.json` means, read about [inputs](/sdk/js/docs/examples/accept-user-input) and [adding data to a dataset](/sdk/js/docs/examples/add-data-to-dataset) in the Apify SDK documentation, and refer to the [input schema docs](/actors/development/actor-definition/input-schema/specification/v1#integer). +If you're interested in learning more about how the code works, and what the `INPUT_SCHEMA.json` means, read about [inputs](/sdk/js/docs/examples/accept-user-input) and [adding data to a dataset](/sdk/js/docs/examples/add-data-to-dataset) in the Apify SDK documentation, and refer to the [input schema docs](/actors/development/actor-definition/input-schema/specification/v1/boolean-and-numeric). ::: diff --git a/sources/platform/actors/development/actor_definition/input_schema/index.md b/sources/platform/actors/development/actor_definition/input_schema/index.md index e0f0df28c3..8b11860485 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/index.md +++ b/sources/platform/actors/development/actor_definition/input_schema/index.md @@ -76,4 +76,4 @@ The actual input object passed from the autogenerated input UI to the Actor then } ``` -Next, let's take a look at [input schema specification](./specification.md), the possibility of using input schema to enable users to pass [secrets](./secret_input.md), and how to define [custom error messages](./custom_error_messages.md) for input validation. +Next, let's take a look at [input schema specification](./specification/index.md), the possibility of using input schema to enable users to pass [secrets](./secret_input.md), and how to define [custom error messages](./custom_error_messages.md) for input validation. diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification.md b/sources/platform/actors/development/actor_definition/input_schema/specification.md deleted file mode 100644 index 14ec9580a2..0000000000 --- a/sources/platform/actors/development/actor_definition/input_schema/specification.md +++ /dev/null @@ -1,1080 +0,0 @@ ---- -title: Actor input schema specification -sidebar_position: 1 -description: Learn how to define and validate a schema for your Actor's input with code examples. Provide an autogenerated input UI for your Actor's users. -slug: /actors/development/actor-definition/input-schema/specification/v1 -toc_max_heading_level: 5 -sidebar_label: 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. - -:::note 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`](/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: - -```json5 -{ - "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](./images/input-schema-example.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: - -```json -{ - "startUrls": [ - { - "url": "http://example.com" - }, - { - "url": "http://example.com/some-path" - } - ], - "pageFunction": "async () => { return $('title').text(); }" -} -``` - -## Structure - -```json -{ - "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. | - -:::note 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 | 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](./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 | 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.).


Defaults to `absolute`. | - -:::note 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: - -```json -{ - "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](./images/input-schema-country.png) - -##### 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: - -![Apify Actor input schema - tag input suggestion](./images/input-schema-tag-suggestion.png) - -#### Code editor - -If the input string is code, you can use either `javascript` or `python` editor -for syntax highlighting. - -For example: - -```json -{ - "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](./images/input-schema-page-function.png) - -#### Date picker - -Example of date selection using absolute and relative `datepicker` editor: - -```json -{ - "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](./images/input-schema-date-absolute.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](./images/input-schema-date-relative.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](./images/input-schema-date-both.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](./images/input-schema-fileupload-input.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](./images/input-schema-fileupload-modal.png) - -### Boolean type - -Example options with group caption: - -```json5 -{ - "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](./images/input-schema-options.png) - -Properties: - -| Property | Value | Required | Description | -| --- | --- | --- | --- | -| `editor` | One of | 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: - -```json -{ - "title": "Memory", - "type": "integer", - "description": "Select memory in megabytes", - "default": 64, - "maximum": 1024, - "unit": "MB" -} -``` - -Rendered input: - -![Apify Actor input schema memory](./images/input-schema-memory.png) - -Properties: - -| Property | Value | Required | Description | -|------------|-----------------------------------------------------|----------|-------------------------------------------------------------------------------| -| `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. | -| `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: - -```json -{ - "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](./images/input-schema-proxy.png) - -The object where the proxy configuration is stored has the following structure: - -```json5 -{ - // 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: - -```json -{ - "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](./images/input-schema-user.png) - -Properties: - -| Property | Value | Required | Description | -|------------------------|----------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `editor` | One of | 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. | - -#### 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. - -:::note Recursive nesting - -Object sub-properties can define their own sub-schemas recursively with no nesting depth limit. - -::: - -```json title="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](./images/sub-schema-json.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: - -```json -{ - "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 [below](#array)), allowing each property to be represented with an appropriate input field in the UI. - -```json title="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](./images/sub-schema-ui.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: - -```json -{ - "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](./images/input-schema-start-urls.png) - -Example of an array: - -```json -{ - "title": "Colors", - "type": "array", - "description": "Enter colors you know", - "prefill": ["Red", "White"], - "editor": "json" -} -``` - -Rendered input: - -![Apify Actor input schema colors array](./images/input-schema-colors.png) - -Properties: - -| Property | Value | Required | Description | -|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `editor` | One of | 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. | - -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: - -```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: - -![Apify Actor input schema - multiselect with predefined values](./images/input-schema-country-multi.png) - -##### Select with custom input - -When you want to suggest values but still allow custom input, use the `enumSuggestedValues` property: - -```json -{ - "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](./images/input-schema-tags-multi-suggestion.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 [Object fields validation](#object-fields-validation)). - -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. - -```json title="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](./images/sub-schema-array-json.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 [Object fields validation](#object-fields-validation)). - -##### 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: - -```json -{ - "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: - -```json -[ - { "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. - -```json title="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](./images/sub-schema-array-string.png) - -- Each item is rendered as a text field. -- The array must contain between 1 and 50 items. -- Duplicate values are not allowed. - -```json title="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](./images/sub-schema-array-object.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. - -Supported resource types are storage resources (dataset, key-value store, request queue) and [MCP connectors](/integrations/mcp-connectors), which let an Actor call third-party MCP servers using credentials the user has authorized in their account. - -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: - -```json -{ - "title": "Dataset", - "type": "string", - "description": "Select a dataset", - "resourceType": "dataset" -} -``` - -Rendered input: - -![Apify Actor input schema dataset](./images/input-schema-dataset.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](./images/input-schema-dataset-json.png) - -Example of multiple datasets input: - -```json -{ - "title": "Datasets", - "type": "array", - "description": "Select multiple datasets", - "resourceType": "dataset", - "resourcePermissions": ["READ"] -} -``` - -Rendered input: - -![Apify Actor input schema datasets](./images/input-schema-datasets.png) - -#### Single value properties - -| Property | Value | Required | Description | -| --- | --- | --- | --- | -| `type` | `string` | Yes | Specifies the type of input - `string` for single value. | -| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. | -| `resourceType` | One of | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept an [MCP connector](/integrations/mcp-connectors) as input. | -| `resourcePermissions` | Array of strings; allowed values: | Yes for storage resources; not used for `mcpConnector` | 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 | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept [MCP connectors](/integrations/mcp-connectors) as input. | -| `resourcePermissions` | Array of strings; allowed values: | Yes for storage resources; not used for `mcpConnector` | 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](../../permissions/index.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. - -:::note 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](../../../running/permissions.md#view-permission-levels-in-apify-console-and-apify-store). - -::: - -#### MCP connector resource type - -When `resourceType` is `mcpConnector`, the input field accepts one or more [MCP connectors](/integrations/mcp-connectors) the user has authorized in their account. The Actor receives the connector ID (or an array of IDs) as the input value and connects to the upstream MCP server through the Apify MCP Proxy at runtime. - -The `mcpConnector` resource type does not use `resourcePermissions`. Instead, eligibility and per-tool access are declared through a required `mcpServers` field, which lists the upstream MCP server URLs and tool constraints the Actor accepts: - -```json -{ - "slackConnector": { - "title": "Slack connector", - "description": "Read-only access to your Slack workspace", - "type": "string", - "resourceType": "mcpConnector", - "mcpServers": [ - { - "url": "https://mcp.slack.com/mcp", - "tools": { - "required": ["list_*", "get_*", "read_*"], - "readOnly": true - } - } - ] - } -} -``` - -The same declaration acts as both eligibility filter (the input picker only offers compatible connectors) and runtime ceiling (the proxy rejects tool calls outside the declared set). For the full `mcpServers` schema, behavioral hints, and code samples, see [Build Actors with MCP connectors](/integrations/mcp-connectors/use-in-actors). - -### Removal of `patternKey` and `patternValue` {#deprecation-of-patternkey-and-patternvalue} - -::::warning Removed properties -**The following properties were deprecated, with support ending on June 30, 2026, and are no longer supported:** - -- `patternKey` - Used to validate keys in objects and arrays -- `patternValue` - Used to validate values in objects and arrays - -Building an Actor whose input schema contains them fails with a validation error. Existing builds are not affected, but you need to migrate your input schema before you build the Actor again. -:::: - -These properties were removed 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: - -```json title="Old approach with patternValue" -{ - "title": "Tags", - "type": "array", - "description": "Enter tags", - "editor": "stringList", - "patternValue": "^[a-zA-Z0-9-_]+$" -} -``` - -```json title="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: - -```json title="Old approach with patternKey and patternValue" -{ - "title": "Headers", - "type": "array", - "description": "HTTP headers", - "editor": "keyValue", - "patternKey": "^[a-zA-Z0-9-]+$", - "patternValue": "^.+$" -} -``` - -```json title="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 no direct replacement for `patternKey` and `patternValue` properties. - -If you need to validate object properties, consider using a predefined schema with the `properties` field instead of allowing arbitrary properties with validation patterns. diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/_category_.json b/sources/platform/actors/development/actor_definition/input_schema/specification/_category_.json new file mode 100644 index 0000000000..508c6eb439 --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Input schema specification", + "position": 1, + "collapsed": true +} diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/array.md b/sources/platform/actors/development/actor_definition/input_schema/specification/array.md new file mode 100644 index 0000000000..48f6828237 --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/array.md @@ -0,0 +1,293 @@ +--- +title: Array input type +sidebar_label: Array +sidebar_position: 4 +description: Define array input fields in an Actor input schema - start URL lists, key-value pairs, multiselect, item validation, and the schema-based editor. +slug: /actors/development/actor-definition/input-schema/specification/v1/array +--- + +Array fields hold a list of values. The editor decides how users enter them, from a URL list to key-value pairs or a multiselect, and an optional `items` sub-schema validates each item. + +Example of request list sources configuration: + +```json +{ + "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](../images/input-schema-start-urls.png) + +Example of an array: + +```json +{ + "title": "Colors", + "type": "array", + "description": "Enter colors you know", + "prefill": ["Red", "White"], + "editor": "json" +} +``` + +Rendered input: + +![Apify Actor input schema colors array](../images/input-schema-colors.png) + +Properties: + +| Property | Value | Required | Description | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `editor` | One of | 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. | + +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: + +```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: + +![Apify Actor input schema - multiselect with predefined values](../images/input-schema-country-multi.png) + +### Select with custom input + +When you want to suggest values but still allow custom input, use the `enumSuggestedValues` property: + +```json +{ + "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](../images/input-schema-tags-multi-suggestion.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 [Object fields validation](./object.md#object-fields-validation)). + +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. + +```json title="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](../images/sub-schema-array-json.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 [Object fields validation](./object.md#object-fields-validation)). + +### 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: + +```json +{ + "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: + +```json +[ + { "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. + +```json title="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](../images/sub-schema-array-string.png) + +- Each item is rendered as a text field. +- The array must contain between 1 and 50 items. +- Duplicate values are not allowed. + +```json title="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](../images/sub-schema-array-object.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. diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/boolean-and-numeric.md b/sources/platform/actors/development/actor_definition/input_schema/specification/boolean-and-numeric.md new file mode 100644 index 0000000000..9b7315f4b2 --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/boolean-and-numeric.md @@ -0,0 +1,81 @@ +--- +title: Boolean and numeric input types +sidebar_label: Boolean and numeric +sidebar_position: 2 +description: Define boolean and numeric input fields in an Actor input schema - checkboxes with group captions, integers and numbers with ranges and units. +slug: /actors/development/actor-definition/input-schema/specification/v1/boolean-and-numeric +--- + +Boolean fields render as checkboxes and can be grouped under a caption. Numeric fields come in two types, `integer` and `number`, and can carry a range and a unit. + +## Boolean type + +Example options with group caption: + +```json5 +{ + "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](../images/input-schema-options.png) + +Properties: + +| Property | Value | Required | Description | +| --- | --- | --- | --- | +| `editor` | One of | 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: + +```json +{ + "title": "Memory", + "type": "integer", + "description": "Select memory in megabytes", + "default": 64, + "maximum": 1024, + "unit": "MB" +} +``` + +Rendered input: + +![Apify Actor input schema memory](../images/input-schema-memory.png) + +Properties: + +| Property | Value | Required | Description | +|------------|-----------------------------------------------------|----------|-------------------------------------------------------------------------------| +| `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. | +| `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. | diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/index.md b/sources/platform/actors/development/actor_definition/input_schema/specification/index.md new file mode 100644 index 0000000000..872424822c --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/index.md @@ -0,0 +1,239 @@ +--- +title: Actor input schema specification +sidebar_position: 1 +description: Define and validate the input your Actor accepts, and get an autogenerated input UI for its users. +slug: /actors/development/actor-definition/input-schema/specification/v1 +toc_max_heading_level: 5 +sidebar_label: 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. + +:::note 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`](/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: + +```json5 +{ + "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](../images/input-schema-example.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: + +```json +{ + "startUrls": [ + { + "url": "http://example.com" + }, + { + "url": "http://example.com/some-path" + } + ], + "pageFunction": "async () => { return $('title').text(); }" +} +``` + +## Structure + +```json +{ + "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. | + +:::note 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 | 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](../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. Each type has its own page with its editors, validation properties, and examples: + +| Type | Editors | Typical use | +| --- | --- | --- | +| [String](./string.md) | `textfield`, `textarea`, `javascript`, `python`, `select`, `datepicker`, `fileupload`, `hidden` | Text, code, dates, single choice, one file | +| [Boolean and numeric](./boolean-and-numeric.md) | `checkbox`, `number`, `hidden` | Flags and option groups, integers and floating-point numbers with units and ranges | +| [Object](./object.md) | `json`, `proxy`, `schemaBased`, `hidden` | Proxy configuration, free-form objects, objects with a validated sub-schema | +| [Array](./array.md) | `json`, `requestListSources`, `pseudoUrls`, `globs`, `keyValue`, `stringList`, `fileupload`, `select`, `schemaBased`, `hidden` | Start URLs, lists, key-value pairs, multiple choice, arrays with validated items | +| [Resource](./resource.md) | `resourcePicker`, `textfield`, `hidden` | A dataset, key-value store, request queue, or MCP connector the user picks from their account | + +The `patternKey` and `patternValue` properties were removed on June 30, 2026. See [Removal of `patternKey` and `patternValue`](#deprecation-of-patternkey-and-patternvalue) for what replaces them. + +## Removal of `patternKey` and `patternValue` {#deprecation-of-patternkey-and-patternvalue} + +::::warning Removed properties +The `patternKey` and `patternValue` properties were removed from the input schema on June 30, 2026. A build whose input schema still contains either property fails with a validation error. Existing builds keep running. Replace both properties before you build the Actor again. +:::: + +The two properties validated keys and values in objects and arrays. Their replacements are standard [JSON schema](https://json-schema.org/), which also lets you validate 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: + +```json title="Old approach with patternValue" +{ + "title": "Tags", + "type": "array", + "description": "Enter tags", + "editor": "stringList", + "patternValue": "^[a-zA-Z0-9-_]+$" +} +``` + +```json title="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: + +```json title="Old approach with patternKey and patternValue" +{ + "title": "Headers", + "type": "array", + "description": "HTTP headers", + "editor": "keyValue", + "patternKey": "^[a-zA-Z0-9-]+$", + "patternValue": "^.+$" +} +``` + +```json title="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 no direct replacement for `patternKey` and `patternValue` properties. + +If you need to validate object properties, consider using a predefined schema with the `properties` field instead of allowing arbitrary properties with validation patterns. diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/object.md b/sources/platform/actors/development/actor_definition/input_schema/specification/object.md new file mode 100644 index 0000000000..ac830d101d --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/object.md @@ -0,0 +1,233 @@ +--- +title: Object input type +sidebar_label: Object +sidebar_position: 3 +description: Define object input fields in an Actor input schema - proxy configuration, free-form JSON, sub-schema validation, and the schema-based editor. +slug: /actors/development/actor-definition/input-schema/specification/v1/object +--- + +Object fields hold a nested value. The editor decides whether users see a proxy picker, a JSON editor, or one input per sub-property, and an optional sub-schema validates the sub-properties. + +Example of proxy configuration: + +```json +{ + "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](../images/input-schema-proxy.png) + +The object where the proxy configuration is stored has the following structure: + +```json5 +{ + // 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: + +```json +{ + "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](../images/input-schema-user.png) + +Properties: + +| Property | Value | Required | Description | +|------------------------|----------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `editor` | One of | 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. | + +## 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. + +:::note Recursive nesting + +Object sub-properties can define their own sub-schemas recursively with no nesting depth limit. + +::: + +```json title="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](../images/sub-schema-json.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: + +```json +{ + "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 [Array](./array.md)), allowing each property to be represented with an appropriate input field in the UI. + +```json title="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](../images/sub-schema-ui.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`. diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/resource.md b/sources/platform/actors/development/actor_definition/input_schema/specification/resource.md new file mode 100644 index 0000000000..7a7e68aab7 --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/resource.md @@ -0,0 +1,114 @@ +--- +title: Resource input type +sidebar_label: Resource +sidebar_position: 5 +description: Let users pick a dataset, key-value store, request queue, or MCP connector as Actor input, and declare the permissions it needs. +slug: /actors/development/actor-definition/input-schema/specification/v1/resource +--- + +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. + +Supported resource types are storage resources (dataset, key-value store, request queue) and [MCP connectors](/integrations/mcp-connectors), which let an Actor call third-party MCP servers using credentials the user has authorized in their account. + +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: + +```json +{ + "title": "Dataset", + "type": "string", + "description": "Select a dataset", + "resourceType": "dataset" +} +``` + +Rendered input: + +![Apify Actor input schema dataset](../images/input-schema-dataset.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](../images/input-schema-dataset-json.png) + +Example of multiple datasets input: + +```json +{ + "title": "Datasets", + "type": "array", + "description": "Select multiple datasets", + "resourceType": "dataset", + "resourcePermissions": ["READ"] +} +``` + +Rendered input: + +![Apify Actor input schema datasets](../images/input-schema-datasets.png) + +## Single value properties + +| Property | Value | Required | Description | +| --- | --- | --- | --- | +| `type` | `string` | Yes | Specifies the type of input - `string` for single value. | +| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. | +| `resourceType` | One of | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept an [MCP connector](/integrations/mcp-connectors) as input. | +| `resourcePermissions` | Array of strings; allowed values: | Yes for storage resources; not used for `mcpConnector` | 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 | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept [MCP connectors](/integrations/mcp-connectors) as input. | +| `resourcePermissions` | Array of strings; allowed values: | Yes for storage resources; not used for `mcpConnector` | 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](../../../permissions/index.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. + +:::note 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](../../../../running/permissions.md#view-permission-levels-in-apify-console-and-apify-store). + +::: + +## MCP connector resource type + +When `resourceType` is `mcpConnector`, the input field accepts one or more [MCP connectors](/integrations/mcp-connectors) the user has authorized in their account. The Actor receives the connector ID (or an array of IDs) as the input value and connects to the upstream MCP server through the Apify MCP Proxy at runtime. + +The `mcpConnector` resource type does not use `resourcePermissions`. Instead, eligibility and per-tool access are declared through a required `mcpServers` field, which lists the upstream MCP server URLs and tool constraints the Actor accepts: + +```json +{ + "slackConnector": { + "title": "Slack connector", + "description": "Read-only access to your Slack workspace", + "type": "string", + "resourceType": "mcpConnector", + "mcpServers": [ + { + "url": "https://mcp.slack.com/mcp", + "tools": { + "required": ["list_*", "get_*", "read_*"], + "readOnly": true + } + } + ] + } +} +``` + +The same declaration acts as both eligibility filter (the input picker only offers compatible connectors) and runtime ceiling (the proxy rejects tool calls outside the declared set). For the full `mcpServers` schema, behavioral hints, and code samples, see [Build Actors with MCP connectors](/integrations/mcp-connectors/use-in-actors). diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification/string.md b/sources/platform/actors/development/actor_definition/input_schema/specification/string.md new file mode 100644 index 0000000000..f411ccd930 --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/specification/string.md @@ -0,0 +1,158 @@ +--- +title: String input type +sidebar_label: String +sidebar_position: 1 +description: Define string input fields in an Actor input schema - text and code editors, select with fixed or suggested values, date pickers, and file upload. +slug: /actors/development/actor-definition/input-schema/specification/v1/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 | 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.).


Defaults to `absolute`. | + +:::note 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: + +```json +{ + "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](../images/input-schema-country.png) + +### 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: + +![Apify Actor input schema - tag input suggestion](../images/input-schema-tag-suggestion.png) + +## Code editor + +If the input string is code, you can use either `javascript` or `python` editor +for syntax highlighting. + +For example: + +```json +{ + "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](../images/input-schema-page-function.png) + +## Date picker + +Example of date selection using absolute and relative `datepicker` editor: + +```json +{ + "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](../images/input-schema-date-absolute.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](../images/input-schema-date-relative.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](../images/input-schema-date-both.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](../images/input-schema-fileupload-input.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](../images/input-schema-fileupload-modal.png) diff --git a/sources/platform/actors/development/permissions/index.md b/sources/platform/actors/development/permissions/index.md index 52000d6f3d..b28a8fd79e 100644 --- a/sources/platform/actors/development/permissions/index.md +++ b/sources/platform/actors/development/permissions/index.md @@ -125,7 +125,7 @@ Behavior at run time: - The user’s selection is injected into the run input, and the run token is expanded to allow only the requested operations on the selected storages. - If your code attempts an operation not covered by `resourcePermissions` (for example, writing with only `READ`), the platform returns an insufficient-permissions error. -See the full [input schema reference for details](../actor_definition/input_schema/specification.md). +See the full [input schema reference for details](../actor_definition/input_schema/specification/index.md). ### Request full permissions diff --git a/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md b/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md index 70994e1867..207a50acc6 100644 --- a/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md +++ b/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md @@ -455,6 +455,6 @@ For the full schema, see [The `mcpServers` rule list](#the-mcpservers-rule-list) ## Related pages - [MCP connectors overview](/integrations/mcp-connectors) -- [Input schema specification - resource type](/actors/development/actor-definition/input-schema/specification/v1#resource-type) +- [Input schema specification - resource type](/actors/development/actor-definition/input-schema/specification/v1/resource) - [Account settings - MCP connectors](/account/settings#mcp-connectors) - [Apify environment variables](/actors/development/programming-interface/environment-variables#system-environment-variables)