From 78139bf0d3f4c509f232bf32e134cdfd69938aee Mon Sep 17 00:00:00 2001 From: Jan Buchar Date: Tue, 10 Jun 2025 14:35:09 +0200 Subject: [PATCH 1/2] docs: Improve prefill documentation --- .../actor_definition/input_schema/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification.md b/sources/platform/actors/development/actor_definition/input_schema/specification.md index 6ada8db012..60c57ca45d 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/specification.md +++ b/sources/platform/actors/development/actor_definition/input_schema/specification.md @@ -132,13 +132,13 @@ Each field of your input is described under its key in the `inputSchema.properti 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. +- **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 - the Default will (if specified). - **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**, but the combinations **Prefill + Default** or **Default + Required** don't make sense to use. +In summary, you can use each option independently or use a combination of **Prefill + Required** or **Prefill + Default** (for example to maintain backward compatibility when introducing a new flag or feature), but the combinations of **Default + Required** doesn't make sense to use. ## Additional properties From 57da8cd6856cdf6b15f4f329653f1c712a312f2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Curn?= Date: Tue, 10 Jun 2025 15:00:15 +0200 Subject: [PATCH 2/2] Update specification.md --- .../actor_definition/input_schema/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification.md b/sources/platform/actors/development/actor_definition/input_schema/specification.md index 60c57ca45d..838bab422d 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/specification.md +++ b/sources/platform/actors/development/actor_definition/input_schema/specification.md @@ -132,13 +132,13 @@ Each field of your input is described under its key in the `inputSchema.properti 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 - the Default will (if specified). +- **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** (for example to maintain backward compatibility when introducing a new flag or feature), but the combinations of **Default + Required** doesn't make sense to use. +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. ## Additional properties