Actor input schema

Actor input schema defines input that actor accepts and the UI components used for input at Apify platform. Input schema must be stored in a file named INPUT_SCHEMA.json in the root directory of the actor. Maximum size of input schema file is 100 kB.

Example

{
    "title": "Cheerio Crawler input",
    "type": "object",
    "schemaVersion": 1,
    "properties": {
        "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "URLs to start with",
            "default": [
                { "url": "http://example.com" }
            ],
            "editor": "requestListSources"
        },
        "pageFunction": {
            "title": "Page function",
            "type": "string",
            "description": "Function executed for each request",
            "default": "async () => {\n  return $('title').text();\n\n}",
            "editor": "javascript"
        }
    },
    "required": ["startUrls", "pageFunction"]
}

Structure

Input schema file must have following structure:
{
    "title": "Cheerio Crawler input",
    "type": "object",
    "schemaVersion": 1,
    "properties": {},
    "required": []
}
Property Type Required Description
title String Yes Any text describing your input schema.
value String Yes This is fixed and must be set to string Object
schemaVersion Integer Yes Version of input schema specification against your schema is written. Currently only 1 is supported.
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.

Fields

Each field of your input is described under its key in inputSchema.properties object. Field might have integer, string, array, object and boolean type and its specification may contain following properties:

Property Value Required Description
type One of string, array, object, boolean, integer Yes Allowed type for the input value. Cannot be mixed.
title String Yes Title of the field in UI.
description String Yes Description of the field that will be displayed as help text in Actor input UI.
default Must match type property. No Default value that will be used when no value is provided.
prefill Must match type property. No Value that will be prefilled in the actor input interface. Only the boolean type doesn't support prefill property.

Additional properties

In addition to that properties listed above, the most of the types support also additional properties defining for example UI input editor.

String

Example of code input:

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

Example of country selection using select input:

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

Properties:

Property Value Required Description
editor One of json, textfield, textarea, javascript No Visual editor used for input field.
maxLength Integer No Maximum length of the string.
enum [String] No Using this field you can limit values to the given array se of strings. Input will be displayed as select box.
enumTiles [String] No Titles for the enum keys described.

Boolean

Example:

{
    "title": "Verbose log",
    "type": "boolean",
    "description": "Debug messages will be included in the log.",
    "default": true
}

Properties:

Property Value Required Description
groupCaption String No If you want to group multiple checkboxes together add this option to the first one.
groupDescription String No Description displayed as help text displayed of group title.

Integer

Example:

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

Properties:

Property Value Required Description
maximum Integer No Maximum allowed value.
minimum Integer No Minimum allowed value
unit String> No Unit displayed next to the field in UI. For example second, MB, etc.

Object

Example of proxy configuration:

{
    "title": "Proxy configuration",
    "type": "object",
    "description": "Optionaly use Apify Proxy",
    "default": { "userApifyProxy": true },
    "editor": "proxy"
}

Example of an blackbox object:

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

Properties:

Property Value Required Description
editor One of json, proxy Yes UI editor used for input.

Array

Example of request list sources configuration:

{
    "title": "Start URLs",
    "type": "array",
    "description": "URLs to start with",
    "default": [{ "url": "http://example.com" }],
    "editor": "request-list-sources"
}

Example of an array:

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

Properties:

Property Value Required Description
editor One of json, requestListSources, pseudoUrls Yes UI editor used for input.