docs: split the input schema specification into one page per type

sources/academy/platform/deploying_your_code/input_schema.md

@@ -61,7 +61,7 @@ Each property's key corresponds to the name we're expecting within our code, whi
 
 ## Property types & editor types {#property-types}
 
-Within our new **numbers** property, there are two more fields we must specify. Firstly, we must let the platform know that we're expecting an array of numbers with the **type** field. Then, we should also instruct Apify on which UI component to render for this input property. In our case, we have an array of numbers, which means we should use the **json** editor type that we discovered in the ["array" section](/actors/development/actor-definition/input-schema/specification/v1#array) of the input schema documentation. We could also use **stringList**, but then we'd have to parse out the numbers from the strings.
+Within our new **numbers** property, there are two more fields we must specify. First, we must let the platform know that we're expecting an array of numbers with the **type** field. Then, we should also instruct Apify on which UI component to render for this input property. In our case, we have an array of numbers, which means we should use the **json** editor type that we discovered in the ["array" section](/actors/development/actor-definition/input-schema/specification/v1/array) of the input schema documentation. We could also use **stringList**, but then we'd have to parse out the numbers from the strings.
 
 ```json
 {

sources/academy/platform/getting_started/inputs_outputs.md

@@ -69,7 +69,7 @@ This step isn't necessary, as the Actor will still be able to take input in JSON
 
 :::tip Learn more
 
-If you're interested in learning more about how the code works, and what the `INPUT_SCHEMA.json` means, read about [inputs](/sdk/js/docs/examples/accept-user-input) and [adding data to a dataset](/sdk/js/docs/examples/add-data-to-dataset) in the Apify SDK documentation, and refer to the [input schema docs](/actors/development/actor-definition/input-schema/specification/v1#integer).
+If you're interested in learning more about how the code works, and what the `INPUT_SCHEMA.json` means, read about [inputs](/sdk/js/docs/examples/accept-user-input) and [adding data to a dataset](/sdk/js/docs/examples/add-data-to-dataset) in the Apify SDK documentation, and refer to the [input schema docs](/actors/development/actor-definition/input-schema/specification/v1/boolean-and-numeric).
 
 :::
 

sources/platform/actors/development/actor_definition/input_schema/index.md

@@ -76,4 +76,4 @@ The actual input object passed from the autogenerated input UI to the Actor then
 }
 ```
 
-Next, let's take a look at [input schema specification](./specification.md), the possibility of using input schema to enable users to pass [secrets](./secret_input.md), and how to define [custom error messages](./custom_error_messages.md) for input validation.
+Next, let's take a look at [input schema specification](./specification/index.md), the possibility of using input schema to enable users to pass [secrets](./secret_input.md), and how to define [custom error messages](./custom_error_messages.md) for input validation.

sources/platform/actors/development/actor_definition/input_schema/specification/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Input schema specification",
+  "position": 1,
+  "collapsed": true
+}

sources/platform/actors/development/actor_definition/input_schema/specification/boolean-and-numeric.md

@@ -0,0 +1,81 @@
+---
+title: Boolean and numeric input types
+sidebar_label: Boolean and numeric
+sidebar_position: 2
+description: Define boolean and numeric input fields in an Actor input schema - checkboxes with group captions, integers and numbers with ranges and units.
+slug: /actors/development/actor-definition/input-schema/specification/v1/boolean-and-numeric
+---
+
+Boolean fields render as checkboxes and can be grouped under a caption. Numeric fields come in two types, `integer` and `number`, and can carry a range and a unit.
+
+## Boolean type
+
+Example options with group caption:
+
+```json5
+{
+    "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 the
+            speed of light.",
+        "prefill": true
+    }
+}
+```
+
+Rendered input:
+
+![Apify Actor input schema options](../images/input-schema-options.png)
+
+Properties:
+
+| Property | Value | Required | Description |
+| --- | --- | --- | --- |
+| `editor` | One of <ul><li>`checkbox`</li><li>`hidden`</li></ul> | No | Visual editor used for the input field. |
+| `groupCaption` | String | No | If you want to group <br/>multiple checkboxes together, <br/>add this option to the first <br/>of the group. |
+| `groupDescription` | String | No | Description displayed as help text <br/>displayed of group title. |
+| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
+
+## Numeric types
+
+There are two numeric types supported in the input schema: `integer` and `number`.
+
+- The `integer` type represents whole numbers.
+- The `number` type can represent both integers and floating-point numbers.
+
+Example:
+
+```json
+{
+    "title": "Memory",
+    "type": "integer",
+    "description": "Select memory in megabytes",
+    "default": 64,
+    "maximum": 1024,
+    "unit": "MB"
+}
+```
+
+Rendered input:
+
+![Apify Actor input schema memory](../images/input-schema-memory.png)
+
+Properties:
+
+| Property   | Value                                               | Required | Description                                                                   |
+|------------|-----------------------------------------------------|----------|-------------------------------------------------------------------------------|
+| `type`     | One of <ul><li>`integer`</li><li>`number`</li></ul> | Yes      | Defines the type of the field - either an integer or a floating-point number. |
+| `editor`   | One of: <ul><li>`number`</li><li>`hidden`</li></ul> | No       | Visual editor used for input field.                                           |
+| `maximum`  | Integer or Number <br/>(based on the `type`)        | No       | Maximum allowed value.                                                        |
+| `minimum`  | Integer or Number <br/>(based on the `type`)        | No       | Minimum allowed value.                                                        |
+| `unit`     | String                                              | No       | Unit displayed next to the field in UI, <br/>for example _second_, _MB_, etc. |
+| `nullable` | Boolean                                             | No       | Specifies whether null is an allowed value.                                   |

sources/platform/actors/development/actor_definition/input_schema/specification/index.md

@@ -0,0 +1,239 @@
+---
+title: Actor input schema specification
+sidebar_position: 1
+description: Define and validate the input your Actor accepts, and get an autogenerated input UI for its users.
+slug: /actors/development/actor-definition/input-schema/specification/v1
+toc_max_heading_level: 5
+sidebar_label: Input schema specification
+---
+
+Actor input schema is a JSON file which defines the schema and description of the input object and its properties accepted by the Actor on start. The file adheres to [JSON schema](https://json-schema.org/) with our extensions, and describes a single Actor input object and its properties, including documentation, default value, and user interface definition.
+
+The Actor input schema file is used to:
+
+- Validate the passed input JSON object on Actor run, so that Actors don't need to perform input validation and error handling in their code.
+- Render user interface for Actors to make it easy for users to run and test them manually.
+- Generate Actor API documentation and integration code examples on the web or in CLI, making Actors easy to integrate for users.
+- Simplify integration of Actors into automation workflows such as Zapier or Make, by providing smart connectors that smartly pre-populate and link Actor input properties.
+
+To define an input schema for an Actor, set `input` field in the `.actor/actor.json` file to an input schema object (described below), or path to a JSON file containing the input schema object.
+For backwards compatibility, if the `input` field is omitted, the system looks for an `INPUT_SCHEMA.json` file either in the `.actor` directory or the Actor's top-level directory - but note that this functionality is deprecated and might be removed in the future. The maximum allowed size for the input schema file is 500 kB.
+
+When you provide an input schema, the Apify platform will validate the input data passed to the Actor on start (via the API or Apify Console) to ensure compliance before starting the Actor.
+If the input object doesn't conform the schema, the caller receives an error and the Actor is not started.
+
+:::note Validation aid
+
+You can use our [visual input schema editor](https://apify.github.io/input-schema-editor-react/) to guide you through the creation of the `INPUT_SCHEMA.json` file.
+
+To ensure the input schema is valid, here's a corresponding [JSON schema file](https://github.com/apify/apify-shared-js/blob/master/packages/json_schemas/schemas/input.schema.json).
+
+You can also use the [`apify validate-schema`](/cli/docs/reference#apify-validate-schema-path) command in the Apify CLI.
+
+:::
+
+## Example
+
+Imagine a simple web crawler that accepts an array of start URLs and a JavaScript function to execute on each visited page. The input schema for such a crawler could be defined as follows:
+
+```json5
+{
+    "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 () => { return $('title').text(); }",
+            "editor": "javascript"
+        }
+    },
+    "required": ["startUrls", "pageFunction"]
+}
+```
+
+The generated input UI will be:
+
+![Apify Actor input schema example](../images/input-schema-example.png)
+
+If you switch the input to the **JSON** display using the toggle, then you will see the entered input stringified to `JSON`, as it will be passed to the Actor:
+
+```json
+{
+    "startUrls": [
+    {
+        "url": "http://example.com"
+    },
+    {
+        "url": "http://example.com/some-path"
+    }
+    ],
+    "pageFunction": "async () => { return $('title').text(); }"
+}
+```
+
+## Structure
+
+```json
+{
+    "title": "Cheerio Crawler input",
+    "type": "object",
+    "schemaVersion": 1,
+    "properties": { /* define input fields here */ },
+    "required": []
+}
+```
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `title` | String | Yes | Any text describing your input schema. |
+| `description` | String | No | Help text for the input that will be <br/>displayed above the UI fields. |
+| `type` | String | Yes | This is fixed and must be set <br/>to string `object`. |
+| `schemaVersion` | Integer | Yes | The version of the input schema <br/>specification against which <br/>your schema is written. Currently, only version `1` is out. |
+| `properties` | Object | Yes | This is an object mapping each field key <br/>to its specification. |
+| `required` | String | No | An array of field keys that are required. |
+| `additionalProperties` | Boolean | No | Controls if properties not listed in `properties` are allowed. Defaults to `true`. <br/>Set to `false` to make requests with extra properties fail. |
+
+:::note Input schema differences
+
+Even though the structure of the Actor input schema is similar to JSON schema, there are some differences. We cannot guarantee that JSON schema tooling will work on input schema documents. For a more precise technical understanding of the matter, feel free to browse the code of the [@apify/input_schema](https://github.com/apify/apify-shared-js/tree/master/packages/input_schema/src) package.
+
+:::
+
+## Input fields
+
+Each field of your input is described under its key in the `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 <ul><li>`string`</li><li>`array`</li><li>`object`</li><li>`boolean`</li><li>`integer`</li></ul> | Yes | Allowed type for the input value. <br/>Cannot be mixed. |
+| `title` | String | Yes | Title of the field in UI. |
+| `description` | String | Yes | Description of the field that will be <br/>displayed as help text in Actor input UI. |
+| `default` | Must match `type` property. | No | Default value that will be <br/>used when no value is provided. |
+| `prefill` | Must match `type` property. | No | Value that will be prefilled <br/>in the Actor input interface. |
+| `example` | Must match `type` property. | No | Sample value of this field <br/>for the Actor to be displayed when <br/>Actor is published in Apify Store. |
+| `errorMessage` | Object | No | Custom error messages for validation keywords. <br/>See [custom error messages](../custom_error_messages.md) <br/>for more details. |
+| `sectionCaption` | String | No | If this property is set, <br/>then all fields following this field <br/>(this field included) will be separated <br/>into a collapsible section <br/>with the value set as its caption. The section ends at the last field <br/>or the next field which has the <br/> `sectionCaption` property set. |
+| `sectionDescription` | String | No | If the `sectionCaption` property is set, <br/>then you can use this property to <br/>provide additional description to the section. <br/>The description will be visible right under <br/>the caption when the section is open. |
+
+### Prefill vs. default vs. required
+
+Here is a rule of thumb for whether an input field should have a `prefill`, `default`, or be required:
+
+- **Prefill** - Use for fields that don't have a reasonable default. The provided value is prefilled for the user to show them an example of using the field and to make it easy to test the Actor (e.g., search keyword, start URLs). In other words, this field is only used in the user interface but does not affect the Actor functionality and API. Note that if you add a new input option to your Actor, the Prefill value won't be used by existing integrations such as Actor tasks or API calls, but the Default will be if specified. This is useful for keeping backward compatibility when introducing a new flag or feature that you prefer new users to use.
+- **Required** - Use for fields that don't have a reasonable default and MUST be entered by the user (e.g., API token, password).
+- **Default** - Use for fields that MUST be set for the Actor run to some value, but where you don't need the user to change the default behavior (e.g., max pages to crawl, proxy settings).
+  If the user omits the value when starting the Actor via any means (API, CLI, scheduler, or user interface), the platform automatically passes the Actor this default value.
+- **No particular setting** - Use for purely optional fields where it makes no sense to prefill any value (e.g., flags like debug mode or download files).
+
+In summary, you can use each option independently or use a combination of **Prefill + Required** or **Prefill + Default**, but the combination of **Default + Required** doesn't make sense to use.
+
+## Input types
+
+Most types also support additional properties defining, for example, the UI input editor. Each type has its own page with its editors, validation properties, and examples:
+
+| Type | Editors | Typical use |
+| --- | --- | --- |
+| [String](./string.md) | `textfield`, `textarea`, `javascript`, `python`, `select`, `datepicker`, `fileupload`, `hidden` | Text, code, dates, single choice, one file |
+| [Boolean and numeric](./boolean-and-numeric.md) | `checkbox`, `number`, `hidden` | Flags and option groups, integers and floating-point numbers with units and ranges |
+| [Object](./object.md) | `json`, `proxy`, `schemaBased`, `hidden` | Proxy configuration, free-form objects, objects with a validated sub-schema |
+| [Array](./array.md) | `json`, `requestListSources`, `pseudoUrls`, `globs`, `keyValue`, `stringList`, `fileupload`, `select`, `schemaBased`, `hidden` | Start URLs, lists, key-value pairs, multiple choice, arrays with validated items |
+| [Resource](./resource.md) | `resourcePicker`, `textfield`, `hidden` | A dataset, key-value store, request queue, or MCP connector the user picks from their account |
+
+The `patternKey` and `patternValue` properties were removed on June 30, 2026. See [Removal of `patternKey` and `patternValue`](#deprecation-of-patternkey-and-patternvalue) for what replaces them.
+
+## Removal of `patternKey` and `patternValue` {#deprecation-of-patternkey-and-patternvalue}
+
+::::warning Removed properties
+The `patternKey` and `patternValue` properties were removed from the input schema on June 30, 2026. A build whose input schema still contains either property fails with a validation error. Existing builds keep running. Replace both properties before you build the Actor again.
+::::
+
+The two properties validated keys and values in objects and arrays. Their replacements are standard [JSON schema](https://json-schema.org/), which also lets you validate sub-properties.
+
+### Alternatives for arrays
+
+For arrays, you can replace `patternKey` and `patternValue` by using the `items` property with a subschema.
+
+Example of replacing `patternValue` for an array of strings:
+
+```json title="Old approach with patternValue"
+{
+    "title": "Tags",
+    "type": "array",
+    "description": "Enter tags",
+    "editor": "stringList",
+    "patternValue": "^[a-zA-Z0-9-_]+$"
+}
+```
+
+```json title="New approach with items subschema"
+{
+    "title": "Tags",
+    "type": "array",
+    "description": "Enter tags",
+    "editor": "stringList",
+    "items": {
+        "type": "string",
+        "pattern": "^[a-zA-Z0-9-_]+$"
+    }
+}
+```
+
+Example of replacing both `patternKey` and `patternValue` for an array with key-value pairs:
+
+```json title="Old approach with patternKey and patternValue"
+{
+    "title": "Headers",
+    "type": "array",
+    "description": "HTTP headers",
+    "editor": "keyValue",
+    "patternKey": "^[a-zA-Z0-9-]+$",
+    "patternValue": "^.+$"
+}
+```
+
+```json title="New approach with items subschema"
+{
+    "title": "Headers",
+    "type": "array",
+    "description": "HTTP headers",
+    "editor": "keyValue",
+    "items": {
+        "type": "object",
+        "properties": {
+            "key": {
+                "title": "Name",
+                "type": "string",
+                "description": "Header name",
+                "pattern": "^[a-zA-Z0-9-]+$"
+            },
+            "value": {
+                "title": "Value",
+                "type": "string",
+                "description": "Header value",
+                "pattern": "^.+$"
+            }
+        },
+        "required": ["key", "value"]
+    }
+}
+```
+
+### Alternatives for objects
+
+For objects, there is no direct replacement for `patternKey` and `patternValue` properties.
+
+If you need to validate object properties, consider using a predefined schema with the `properties` field instead of allowing arbitrary properties with validation patterns.