Skip to content

docs: updates to formatting #1638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 17, 2025
Merged

docs: updates to formatting #1638

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4878a59
docs: updates to formatting
TC-MO Jun 17, 2025
034e2a5
Merge branch 'master' into update-to-formatting-in-specification
TC-MO Jun 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 20 additions & 11 deletions sources/platform/actors/development/actor_definition/input_schema/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Specification
sidebar_position: 2
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
---

# Actor input schema specification
Expand Down Expand Up @@ -148,6 +149,8 @@ Most types also support additional properties defining, for example, the UI inpu

### String

#### Code input

Example of a code input:

```json
Expand All @@ -164,6 +167,8 @@ Rendered input:

![Apify Actor input schema page function](./images/input-schema-page-function.png)

#### Country selection

Example of country selection using a select input:

```json
Expand All @@ -182,6 +187,8 @@ Rendered input:

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

#### `datepicker` editor

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

```json
Expand Down Expand Up @@ -224,6 +231,8 @@ The `anyDate` property renders a date picker that accepts both absolute and rela

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

#### `fileupload` editor

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.

![Apify Actor input schema - fileupload input](./images/input-schema-fileupload-input.png)
Expand All @@ -234,17 +243,17 @@ The user provides either a URL or uploads the file to a key-value store (existin

Properties:

| Property | Value | Required | Description |
|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `editor` | One of <ul><li>`textfield`</li><li>`textarea`</li><li>`javascript`</li><li>`python`</li><li>`select`</li><li>`datepicker`</li><li>`fileupload`</li><li>`hidden`</li></ul> | Yes | Visual editor used for <br/>the input field. |
| `pattern` | String | No | Regular expression that will be <br/>used to validate the input. <br/> If validation fails, <br/>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 <br/>`editor` <br/>is `select` | Using this field, you can limit values <br/>to the given array of strings. <br/>Input will be displayed as select box. |
| `enumTitles` | [String] | No | Titles for the `enum` keys described. |
| `nullable` | Boolean | No | Specifies whether `null` <br/>is an allowed value. |
| `isSecret` | Boolean | No | Specifies whether the input field<br />will be stored encrypted.<br />Only available <br />with `textfield` and `textarea` editors. |
| `dateType` | One of <ul><li>`absolute`</li><li>`relative`</li><li>`absoluteOrRelative`</li></ul> | 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.).<br/><br/><ul><li>`absolute` value enables date input in `YYYY-MM-DD` format. To parse returned string regex like this can be used: `^(\d{4})-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`.</li><br/><li>`relative` value enables relative date input in <br/>`{number} {unit}` format. <br/>Supported units are: days, weeks, months, years.<br/><br/>The input is passed to the Actor as plain text (e.g., "3 weeks"). To parse it, regex like this can be used: `^(\d+)\s*(day\|week\|month\|year)s?$`.</li><br/><li>`absoluteOrRelative` value enables both absolute and relative formats and user can switch between them. It's up to Actor author to parse a determine actual used format - regexes above can be used to check whether the returned string match one of them.</li></ul><br/>Defaults to `absolute`. |
| Property | Value | Required | Description |
|----------|--------|-----------|-------------|
| `editor` | One of:<br/>- `textfield`<br/>- `textarea`<br/>- `javascript`<br/>- `python`<br/>- `select`<br/>- `datepicker`<br/>- `fileupload`<br/>- `hidden` | Yes | Visual editor used for the input field. |
| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
| `minLength` | Integer | No | Minimum length of the string. |
| `maxLength` | Integer | No | Maximum length of the string. |
| `enum` | [String] | Required if `editor` is `select` | Using this field, you can limit values to the given array of strings. Input will be displayed as select box. |
| `enumTitles` | [String] | No | Titles for the `enum` keys described. |
| `nullable` | Boolean | No | Specifies whether `null` is an allowed value. |
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `textfield` and `textarea` editors. |
| `dateType` | One of <ul><li>`absolute`</li><li>`relative`</li><li>`absoluteOrRelative`</li></ul> | 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.).<br/><br/><ul><li>`absolute` value enables date input in `YYYY-MM-DD` format. To parse returned string regex like this can be used: `^(\d{4})-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`.</li><br/><li>`relative` value enables relative date input in <br/>`{number} {unit}` format. <br/>Supported units are: days, weeks, months, years.<br/><br/>The input is passed to the Actor as plain text (e.g., "3 weeks"). To parse it, regex like this can be used: `^(\d+)\s*(day\|week\|month\|year)s?$`.</li><br/><li>`absoluteOrRelative` value enables both absolute and relative formats and user can switch between them. It's up to Actor author to parse a determine actual used format - regexes above can be used to check whether the returned string match one of them.</li></ul><br/>Defaults to `absolute`. |

:::note Regex escape

Expand Down