From 19d04126b1f7e997c7917d7a554be384582c7726 Mon Sep 17 00:00:00 2001 From: martinforejt Date: Fri, 28 Nov 2025 15:01:20 +0100 Subject: [PATCH 1/5] docs: Custom error messages in the input schema --- .../input_schema/custom_error_messages.md | 112 ++++++++++++++++++ .../actor_definition/input_schema/index.md | 2 +- .../input_schema/specification.md | 1 + 3 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md diff --git a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md new file mode 100644 index 0000000000..dc3f9f0932 --- /dev/null +++ b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md @@ -0,0 +1,112 @@ +--- +title: Custom error messages +description: Learn how to define custom error messages for input validation in your Actor's input schema. Make validation feedback clearer and more user-friendly. +slug: /actors/development/actor-definition/input-schema/custom-error-messages +--- + +**Learn how to define custom error messages for input validation in your Actor's input schema. Make validation feedback clearer and more user-friendly.** + +--- + +When an input fails validation against an Actor's input schema, the resulting errors are processed and displayed to the user. By default, these messages are generic and may not clearly convey the specific semantic meaning behind validation rules. + +Custom error messages allow Actor developers to define tailored feedback messages for input validation errors, making it easier for users to understand what is required and improving overall usability. + +## The problem with generic error messages + +Some validation rules defined by Actor developers carry specific semantic meaning that cannot be clearly conveyed by generic error messages. + +For example, consider the following input field using the `pattern` validation keyword: + +```json +{ + "title": "Email address", + "type": "string", + "description": "Your email address", + "editor": "textfield", + "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" +} +``` + +Input that don't satisfy the pattern, will produce an error message like: + +``` +Field "email" should match pattern "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$". +``` + +However, a message such as the following would be much more understandable for the user: + +``` +Field "email" must be a valid email address. +``` + +## Using the `errorMessage` keyword + +Each property in the [input schema](./index.md) can include an `errorMessage` field that defines custom error messages to be displayed when validation of that field fails. + +The `errorMessage` must be an object that maps *validation keywords* (e.g., `type`, `pattern`, `minLength`) to their respective custom messages. + +```json title="Email input with custom error messages" +{ + "title": "Email address", + "type": "string", + "description": "Your email address", + "editor": "textfield", + "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", + "errorMessage": { + "type": "Email must be a string", + "pattern": "Email must be a valid email address" + } +} +``` + +If a validation error occurs for a keyword that is not listed in the `errorMessage` object, the system will fall back to the default error message. + +::::note +Custom error messages are especially useful for complex validation rules like regular expressions, where the default error message would show the entire pattern, which is not user-friendly. See [best practices](#best-practices) for more guidance. +:::: + +### Supported validation keywords + +You can define custom error messages for any validation keyword supported by the [input schema](./index.md), including: + +| Type | Supported validation keywords | +|--------------------|-----------------------------------------------------------------------------| +| `string` | `type`, `pattern`, `minLength`, `maxLength`, `enum` | +| `number`/`integer` | `type`, `minimum`, `maximum` | +| `boolean` | `type` | +| `array` | `type`, `minItems`, `maxItems`, `uniqueItems`, `patternKey`, `patternValue` | +| `object` | `type`, `minProperties`, `maxProperties`, `patternKey`, `patternValue` | + +#### Nested properties + +It's possible to define custom error messages in sub-properties as well. For objects with nested properties, you can define error messages at any level of nesting: + +```json +{ + "title": "User", + "type": "object", + "description": "Provide user details", + "editor": "schemaBased", + "properties": { + "email": { + "type": "string", + "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", + "errorMessage": { + "pattern": "Please enter a valid email address" + } + } + } +} +``` + +## Best practices + +While custom error messages can improve the user experience by providing clearer guidance, it's generally better to rely on the default error messages unless there's a specific need for customization. Only use custom error messages when they significantly help users understand the requirements better than the default messages. + +If you do decide to use custom error messages, follow these best practices: + +1. **Be specific** - Clearly explain what is required or what went wrong +2. **Be concise** - Keep messages short and to the point +3. **Be helpful** - Provide guidance on how to fix the issue +4. **Be consistent** - Use a similar tone and style across all messages diff --git a/sources/platform/actors/development/actor_definition/input_schema/index.md b/sources/platform/actors/development/actor_definition/input_schema/index.md index ad7b50024c..0d7934e6e6 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/index.md +++ b/sources/platform/actors/development/actor_definition/input_schema/index.md @@ -78,4 +78,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), and the possibility of using input schema to enable users to pass [secrets](./secret_input.md). +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. 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 146a27daa7..5e6539f8d0 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/specification.md +++ b/sources/platform/actors/development/actor_definition/input_schema/specification.md @@ -130,6 +130,7 @@ Each field of your input is described under its key in the `inputSchema.properti | `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. | | `example` | Must match `type` property. | No | Sample value of this field
for the Actor to be displayed when
Actor is published in Apify Store. | +| `errorMessage` | Object | No | Custom error messages for validation keywords.
See [custom error messages](./custom_error_messages.md)
for more details. | | `sectionCaption` | String | No | If this property is set,
then all fields following this field
(this field included) will be separated
into a collapsible section
with the value set as its caption.
The section ends at the last field
or the next field which has the
`sectionCaption` property set. | | `sectionDescription` | String | No | If the `sectionCaption` property is set,
then you can use this property to
provide additional description to the section.
The description will be visible right under
the caption when the section is open. | From 417f58390e15c98ba081399e00b92ea83f5d5afe Mon Sep 17 00:00:00 2001 From: martinforejt Date: Fri, 28 Nov 2025 15:39:02 +0100 Subject: [PATCH 2/5] fix lint --- .../actor_definition/input_schema/custom_error_messages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md index dc3f9f0932..8b91b0afae 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md +++ b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md @@ -30,13 +30,13 @@ For example, consider the following input field using the `pattern` validation k Input that don't satisfy the pattern, will produce an error message like: -``` +```text Field "email" should match pattern "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$". ``` However, a message such as the following would be much more understandable for the user: -``` +```text Field "email" must be a valid email address. ``` From f2c31d7f1871c543f416b2c51f21c6f5eebdc95b Mon Sep 17 00:00:00 2001 From: martinforejt Date: Mon, 1 Dec 2025 17:21:35 +0100 Subject: [PATCH 3/5] address CR --- .../input_schema/custom_error_messages.md | 33 ++++++++++--------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md index 8b91b0afae..39f61b013a 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md +++ b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md @@ -8,15 +8,13 @@ slug: /actors/development/actor-definition/input-schema/custom-error-messages --- -When an input fails validation against an Actor's input schema, the resulting errors are processed and displayed to the user. By default, these messages are generic and may not clearly convey the specific semantic meaning behind validation rules. +When an input fails validation against an Actor's input schema, the resulting errors are processed and displayed to the user. By default, these messages are generic and may not clearly explain what the validation rule actually means. Custom error messages allow Actor developers to define tailored feedback messages for input validation errors, making it easier for users to understand what is required and improving overall usability. ## The problem with generic error messages -Some validation rules defined by Actor developers carry specific semantic meaning that cannot be clearly conveyed by generic error messages. - -For example, consider the following input field using the `pattern` validation keyword: +Some validation rules have a specific purpose that generic error messages don't explain well. For example, consider the following input field using the `pattern` validation keyword: ```json { @@ -28,7 +26,7 @@ For example, consider the following input field using the `pattern` validation k } ``` -Input that don't satisfy the pattern, will produce an error message like: +Input that doesn't satisfy the pattern will produce an error message like: ```text Field "email" should match pattern "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$". @@ -40,9 +38,9 @@ However, a message such as the following would be much more understandable for t Field "email" must be a valid email address. ``` -## Using the `errorMessage` keyword +## Custom error messages for input fields -Each property in the [input schema](./index.md) can include an `errorMessage` field that defines custom error messages to be displayed when validation of that field fails. +Each property in the [input schema](./index.md) can include an `errorMessage` field that defines a custom error message to be displayed when validation of that field fails. The `errorMessage` must be an object that maps *validation keywords* (e.g., `type`, `pattern`, `minLength`) to their respective custom messages. @@ -62,9 +60,11 @@ The `errorMessage` must be an object that maps *validation keywords* (e.g., `typ If a validation error occurs for a keyword that is not listed in the `errorMessage` object, the system will fall back to the default error message. -::::note -Custom error messages are especially useful for complex validation rules like regular expressions, where the default error message would show the entire pattern, which is not user-friendly. See [best practices](#best-practices) for more guidance. -:::: +:::note User-Friendly Messages + +Custom error messages are especially useful for complex validation rules like regular expressions, where the default error message would show the entire pattern, which is not user-friendly. Refer to the [best practices](#best-practices) for more guidance. + +::: ### Supported validation keywords @@ -102,11 +102,12 @@ It's possible to define custom error messages in sub-properties as well. For obj ## Best practices -While custom error messages can improve the user experience by providing clearer guidance, it's generally better to rely on the default error messages unless there's a specific need for customization. Only use custom error messages when they significantly help users understand the requirements better than the default messages. +Custom error messages can be useful in specific cases, but they aren't always necessary. In most situations, the default validation messages are clear enough and ensure consistency across the platform. Use custom messages only when they meaningfully improve clarity—for example, when the default message would expose an unreadable regular expression or fail to explain a non-obvious requirement. + +If you choose to add custom messages, keep the following in mind: -If you do decide to use custom error messages, follow these best practices: +1. Be specific – The message should clarify what went wrong. +1. Be concise – Avoid long or overly detailed explanations. +1. Be helpful – Focus on what the user needs to change. +1. Be consistent – Align with the tone and style used elsewhere in your project. -1. **Be specific** - Clearly explain what is required or what went wrong -2. **Be concise** - Keep messages short and to the point -3. **Be helpful** - Provide guidance on how to fix the issue -4. **Be consistent** - Use a similar tone and style across all messages From 83aeac2fcd2472d8b94b46028e7460804321b6ef Mon Sep 17 00:00:00 2001 From: Martin Forejt Date: Tue, 2 Dec 2025 10:23:24 +0100 Subject: [PATCH 4/5] Update sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md Co-authored-by: Marcel Rebro --- .../actor_definition/input_schema/custom_error_messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md index 39f61b013a..4cee05360e 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md +++ b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md @@ -60,7 +60,7 @@ The `errorMessage` must be an object that maps *validation keywords* (e.g., `typ If a validation error occurs for a keyword that is not listed in the `errorMessage` object, the system will fall back to the default error message. -:::note User-Friendly Messages +:::note User-friendly messages Custom error messages are especially useful for complex validation rules like regular expressions, where the default error message would show the entire pattern, which is not user-friendly. Refer to the [best practices](#best-practices) for more guidance. From faa24058b89636576b3f096ed79bf3a18aa54806 Mon Sep 17 00:00:00 2001 From: martinforejt Date: Tue, 2 Dec 2025 14:33:54 +0100 Subject: [PATCH 5/5] address CR --- .../input_schema/custom_error_messages.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md index 4cee05360e..cea9169224 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md +++ b/sources/platform/actors/development/actor_definition/input_schema/custom_error_messages.md @@ -103,11 +103,3 @@ It's possible to define custom error messages in sub-properties as well. For obj ## Best practices Custom error messages can be useful in specific cases, but they aren't always necessary. In most situations, the default validation messages are clear enough and ensure consistency across the platform. Use custom messages only when they meaningfully improve clarity—for example, when the default message would expose an unreadable regular expression or fail to explain a non-obvious requirement. - -If you choose to add custom messages, keep the following in mind: - -1. Be specific – The message should clarify what went wrong. -1. Be concise – Avoid long or overly detailed explanations. -1. Be helpful – Focus on what the user needs to change. -1. Be consistent – Align with the tone and style used elsewhere in your project. -