Input Schema

An Apify Input Schema is a JSON Schema file located at .actor/input_schema.json that defines exactly what input parameters an actor accepts, including their types, descriptions, default values, validation rules, and UI rendering hints. Apify uses this schema to automatically generate the actor's input form in the Console UI — each field in your schema becomes a form element (text input, dropdown, toggle, code editor, JSON editor) that users fill out before running the actor. The input schema also validates API calls, rejecting inputs that do not conform to declared types and required fields with clear error messages. Input schemas matter because the input form is the first thing users see when they open your actor — it determines whether they understand how to use it in 30 seconds and successfully start their first run, or give up and try a competitor's actor instead. A well-designed input schema with clear descriptions, helpful examples, and sensible defaults is the single biggest factor in actor adoption after the README. On the developer side, input validation prevents your actor from crashing on malformed input, reducing failure rates and maintenance flags. Here is a typical input schema structure: { 'title': 'Product Scraper Input', 'type': 'object', 'schemaVersion': 1, 'required': ['startUrls'], 'properties': { 'startUrls': { 'title': 'Start URLs', 'type': 'array', 'description': 'List of product page URLs to scrape. Example: https://example.com/product/123', 'editor': 'requestListSources' }, 'maxItems': { 'title': 'Maximum results', 'type': 'integer', 'description': 'Maximum number of products to scrape. Set to 0 for unlimited.', 'default': 100, 'minimum': 0 }, 'proxyConfig': { 'title': 'Proxy configuration', 'type': 'object', 'description': 'Select proxy type. Use residential for sites with anti-bot protection.', 'editor': 'proxy', 'default': { 'useApifyProxy': true, 'apifyProxyGroups': ['RESIDENTIAL'] } } } }. The editor property is key to good UI rendering. Available editors include: 'textfield' for short strings (URLs, names), 'textarea' for long text (descriptions, templates), 'json' for complex objects, 'requestListSources' for URL lists with file upload support, 'proxy' for Apify proxy configuration with tier selection, 'select' for enumerated options (renders as a dropdown), 'keyValuePairs' for dynamic key-value input, 'daterange' for date selection, and 'hidden' for internal fields users should not see. Common mistakes with input schemas include missing or vague descriptions. Every field needs a clear description that explains what it does, what format is expected, and includes an example value. 'URL' is a bad description. 'The starting URL of the e-commerce category page to scrape. Example: https://example.com/category/electronics' is a good description. No default values is another major mistake — if your actor can work with sensible defaults, set them so users can click Start without configuring anything. An actor that requires users to fill in 5+ fields before their first run will lose most potential users. Overly complex schemas with 15-20+ fields overwhelm first-time users. Group optional and advanced fields into sections using the sectionCaption and sectionDescription properties, or mark them with a prefix like 'Advanced:' in the title. Keep the required fields to 1-3 at most. Not using the prefill property is a missed opportunity — prefill provides example values that appear as placeholder text in the form, guiding users without committing to a default. For validation, use standard JSON Schema keywords: minimum/maximum for numbers, minLength/maxLength for strings, pattern for regex validation, enum for allowed values, and format for standard formats like 'uri' or 'email'. Apify validates input both in the Console form and in API calls, returning descriptive error messages that reference the field name and expected format. Test your input schema by running your actor with no input (should work with defaults), with minimal input (just required fields), and with intentionally wrong input (should fail with clear errors). This ensures a good user experience across all usage patterns. Related concepts: Actor, Dataset Schema, Actor Build, Actor Run, Store Quality Score.