Apify Input Schema Design 2026: User-Friendly Actor Config

Contains affiliate links. Disclosure.

INPUT_SCHEMA.json defines what your Actor accepts and how the Apify Console renders the input form. Good schema design reduces support tickets and failed runs. Place it in .actor/ or reference it from .actor/actor.json.

What the input schema does

The input schema:

• Validates input before the Actor starts (fail fast, no wasted compute)
• Renders the input form in Apify Console
• Generates API docs and integration code for Zapier, Make, and API callers
• Simplifies automation workflows by exposing clear, typed fields

See the full input schema spec.

Core structure

Every schema needs schemaVersion: 1, type: "object", properties, and optional required:

{
  "title": "Product Monitor Input",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "startUrls": {
      "title": "Start URLs",
      "type": "array",
      "description": "URLs to monitor",
      "editor": "requestListSources",
      "prefill": [{ "url": "https://example.com/product/123" }]
    },
    "maxItems": {
      "title": "Max items",
      "type": "integer",
      "description": "Stop after this many items",
      "default": 100,
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": ["startUrls"]
}

Field types

Type	Use case	Example
string	Keywords, URLs, tokens	Search query, API key
integer	Counts, limits	maxItems, maxConcurrency
boolean	Flags	useProxy, debug
array	URL lists, filters	startUrls, categories
object	Nested config	proxyConfiguration

prefill vs default vs required

From the Apify docs:

Option	When to use
prefill	Example value in the UI. User can change it. Not used when task/API omits the field.
default	Value used when the field is omitted. Backward compatible for integrations.
required	User must provide a value. No safe fallback exists (e.g. API token).

Use default for sensible fallbacks (maxItems, proxy group). Use required for secrets and URLs. Use prefill for sample values (search keyword, start URL) to help first-time users.

Editor choices that improve UX

Editor	Field type	Best for
requestListSources	array	Start URLs, crawl seeds
select + enum	string	Fixed choices (country, mode)
select + enumSuggestedValues	string	Suggested values + custom input
textarea	string	Long text, JSON
javascript / python	string	Code snippets
json	object	Advanced users, raw config

Dropdown example:

{
  "title": "Proxy type",
  "type": "string",
  "editor": "select",
  "default": "RESIDENTIAL",
  "enum": ["RESIDENTIAL", "DATACENTER", "AUTO"],
  "enumTitles": ["Residential", "Datacenter", "Auto"]
}

Proxy configuration field

Expose proxy settings so users can choose groups without editing raw JSON:

{
  "proxyConfiguration": {
    "title": "Proxy configuration",
    "type": "object",
    "editor": "proxy",
    "description": "Use Apify Proxy or custom URLs"
  }
}

The proxy editor renders the standard proxy UI. Read more in the proxy configuration guide.

Validation constraints

Add minimum, maximum, minLength, maxLength, pattern for high-risk fields:

{
  "maxItems": {
    "type": "integer",
    "minimum": 1,
    "maximum": 10000,
    "default": 100
  },
  "apiToken": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9]{20,}$",
    "isSecret": true
  }
}

Set additionalProperties: false at the root to reject unknown keys.

Best practices summary

1. Required vs default: Use default when a safe fallback exists; required only when the Actor cannot run without it.
2. Descriptions: Add a short description for every field—it shows as help text.
3. sampleName: For Store listings, use example or sampleName to show realistic values.
4. Avoid raw JSON for non-technical users: Prefer select, requestListSources, and proxy over json when possible.
5. Validate: Use apify validate-schema .actor or the visual editor before pushing.

Next step

Open an existing Actor, refine one field with better title and validation, then run apify validate-schema. Check the full spec →

Frequently Asked Questions

A JSON file (INPUT_SCHEMA.json) that defines Actor input fields, types, validation, and how the Apify Console renders the input form. It validates input before the Actor starts.

Use default when a safe fallback exists (e.g. maxItems: 100). Use required when the Actor cannot run without user input (e.g. API token, start URLs).

Use type: string, editor: select, and enum (strict) or enumSuggestedValues (allow custom). Add enumTitles for display labels.

Place it in .actor/ or the Actor root. Or reference it in .actor/actor.json via the input field. Max size 500 kB.