Actor input schema

Specification version 1

Actor input schema defines the input that actor accepts and the UI components used for input at Apify platform. Using input schema you can provide UI to actor users that is easy to use and also ensure that input of your actor is valid.

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. If the input schema is provided then input is always validated to fulfill schema when an actor is being started (via API or from run console at Apify platform).

Example

Imagine you are building a simple crawler whose inputs are an array of start URLs and javascript function that will be executed at each page crawler visits. Then the input schema will look as follows:

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

And generated input UI will be:

If you switch input to raw display using a blue switcher then you will see entered input stringified to a JSON format as it will be passed to the actor:

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

Structure

Input schema is a JSON file named INPUT_SCHEMA.json in the root directory of an actor with the following structure:

{
    "title": "Cheerio Crawler input",
    "type": "object",
    "schemaVersion": 1,
    "properties": { /* here is a place for definition of input fields */ },
    "required": []
}
Property Type Required Description
title String Yes Any text describing your input schema.
description String No Help text for 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 input schema specification against 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.

Fields

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

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

Additional properties

In addition to that properties listed above, 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",
    "editor": "javascript",
    "prefill": "async () => {\n  return $('title').text();\n\n}"
}

Rendered input:

Example of country selection using select input:

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

Rendered input:

Properties:

Property Value Required Description
editor One of json, textfield, textarea, javascript, select Yes Visual editor used for input field.
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 se of strings. Input will be displayed as select box.
enumTiles [String] No Titles for the enum keys described.

Boolean

Example options with group caption:

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

Rendered input:

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"
}

Rendered input:

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",
    "prefill": { "useApifyProxy": true },
    "editor": "proxy"
}

Rendered input:

Example of an blackbox object:

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

Rendered input:

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",
    "prefill": [{ "url": "http://example.com" }],
    "editor": "requestListSources"
}

Rendered input:

Example of an array:

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

Rendered input:

Properties:

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

Usage of this field is based on the selected editor: