Skip to content

Commit a984531

Browse files
mforiclaudemarcel-rbro
authored
docs: Deprecation of patternKey and patternValue in input schema (#2153)
Partially resolves apify/apify-core#24338 Community was informed in advance: https://apify.slack.com/archives/C09ELTQEY6R/p1770819418439049 <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation-only change that marks two schema properties as deprecated and adds migration examples; no runtime/code behavior is modified. > > **Overview** > Updates the Actor input schema specification docs to mark `patternKey` and `patternValue` as **deprecated** for both object and array fields, including cross-links to a new deprecation section. > > Adds a dedicated deprecation notice with a support timeline (until May 31, 2026) and a migration guide showing how to replace array validations via `items` subschemas, plus notes that object key/value pattern validation will be removed without a direct replacement. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 1c8896c. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Marcel Rebro <marcel.rebro@apify.com>
1 parent 8c01f3f commit a984531

1 file changed

Lines changed: 101 additions & 15 deletions

File tree

  • sources/platform/actors/development/actor_definition/input_schema

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

Lines changed: 101 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -430,15 +430,15 @@ Properties:
430430
| Property | Value | Required | Description |
431431
|------------------------|----------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
432432
| `editor` | One of <ul><li>`json`</li><li>`proxy`</li><li>`schemaBased`</li><li>`hidden`</li></ul> | Yes | UI editor used for input. |
433-
| `patternKey` | String | No | Regular expression that will be used <br/>to validate the keys of the object. |
434-
| `patternValue` | String | No | Regular expression that will be used <br/>to validate the values of object. |
435433
| `maxProperties` | Integer | No | Maximum number of properties <br/>the object can have. |
436434
| `minProperties` | Integer | No | Minimum number of properties <br/>the object can have. |
437435
| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
438436
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `json` and `hidden` editors. |
439437
| `properties` | Object | No | Defines the sub-schema properties for the object used for validation and UI rendering (`schemaBased` editor). See more info below. |
440438
| `additionalProperties` | Boolean | No | Controls if sub-properties not listed in `properties` are allowed. Defaults to `true`. Set to `false` to make requests with extra properties fail. |
441439
| `required` | String array | No | An array of sub-properties keys that are required. <br />Note: This applies only if the object field itself is present. If the object field is optional and not included in the input, its required subfields are not validated. |
440+
| `patternKey` | String | No | _Deprecated_ (see [migration information](#deprecation-of-patternkey-and-patternvalue)). <br/>Regular expression that will be used to validate the keys of the object. |
441+
| `patternValue` | String | No | _Deprecated_ (see [migration information](#deprecation-of-patternkey-and-patternvalue)). <br/>Regular expression that will be used to validate the values of object. |
442442

443443
#### Object fields validation
444444

@@ -634,19 +634,19 @@ Rendered input:
634634

635635
Properties:
636636

637-
| Property | Value | Required | Description |
638-
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
639-
| `editor` | One of <ul><li>`json`</li><li>`requestListSources`</li><li>`pseudoUrls`</li><li>`globs`</li><li>`keyValue`</li><li>`stringList`</li><li>`fileupload`</li><li>`select`</li><li>`schemaBased`</li><li>`hidden`</li></ul> | Yes | UI editor used for input. |
640-
| `placeholderKey` | String | No | Placeholder displayed for <br/>key field when no value is specified. <br/>Works only with `keyValue` editor. |
641-
| `placeholderValue` | String | No | Placeholder displayed in value field <br/>when no value is provided. <br/>Works only with `keyValue` and <br/>`stringList` editors. |
642-
| `patternKey` | String | No | Regular expression that <br/>will be used to validate <br/>the keys of items in the array. <br/>Works only with `keyValue` <br/>editor. |
643-
| `patternValue` | String | No | Regular expression that <br/>will be used to validate the values <br/>of items in the array. <br/>Works only with `keyValue` and <br/>`stringList` editors. |
644-
| `maxItems` | Integer | No | Maximum number of items <br/>the array can contain. |
645-
| `minItems` | Integer | No | Minimum number of items <br/>the array can contain. |
646-
| `uniqueItems` | Boolean | No | Specifies whether the array <br/>should contain only unique values. |
647-
| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
648-
| `items` | object | No | Specifies format of the items of the array, useful mainly for multiselect and for `schemaBased` editor (see below). |
649-
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `json` and `hidden` editors. |
637+
| Property | Value | Required | Description |
638+
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
639+
| `editor` | One of <ul><li>`json`</li><li>`requestListSources`</li><li>`pseudoUrls`</li><li>`globs`</li><li>`keyValue`</li><li>`stringList`</li><li>`fileupload`</li><li>`select`</li><li>`schemaBased`</li><li>`hidden`</li></ul> | Yes | UI editor used for input. |
640+
| `placeholderKey` | String | No | Placeholder displayed for <br/>key field when no value is specified. <br/>Works only with `keyValue` editor. |
641+
| `placeholderValue` | String | No | Placeholder displayed in value field <br/>when no value is provided. <br/>Works only with `keyValue` and <br/>`stringList` editors. |
642+
| `maxItems` | Integer | No | Maximum number of items <br/>the array can contain. |
643+
| `minItems` | Integer | No | Minimum number of items <br/>the array can contain. |
644+
| `uniqueItems` | Boolean | No | Specifies whether the array <br/>should contain only unique values. |
645+
| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
646+
| `items` | object | No | Specifies format of the items of the array, useful mainly for multiselect and for `schemaBased` editor (see below). |
647+
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `json` and `hidden` editors. |
648+
| `patternKey` | String | No | _Deprecated_ (see [migration information](#deprecation-of-patternkey-and-patternvalue)). <br/>Regular expression that will be used to validate the keys of items in the array. <br/>Works only with `keyValue` <br/>editor. |
649+
| `patternValue` | String | No | _Deprecated_ (see [migration information](#deprecation-of-patternkey-and-patternvalue)). <br/>Regular expression that will be used to validate the values of items in the array. <br/>Works only with `keyValue` and <br/>`stringList` editors. |
650650

651651
Usage of this field is based on the selected editor:
652652

@@ -965,3 +965,89 @@ If your Actor runs with limited permissions, it must declare what access it need
965965
This setting defines runtime access only and doesn't change field visibility or whether the field is required in the UI. For array fields (`type: array`), the same permissions apply to each selected resource. Your Actor's run will fail with an insufficient-permissions error if it attempts an operation without the required permission, such as writing with read-only access. Users can see the required permissions in the [input field's tooltip](../../../running/permissions.md#recognizing-permission-levels-in-console-and-store).
966966

967967
:::
968+
969+
### Deprecation of `patternKey` and `patternValue`
970+
971+
::::warning Deprecation notice
972+
**The following properties are deprecated and will only be supported until June 30, 2026:**
973+
974+
- `patternKey` - Used to validate keys in objects and arrays
975+
- `patternValue` - Used to validate values in objects and arrays
976+
::::
977+
978+
These properties are being deprecated to better align with the JSON schema specification. By moving to standard JSON schema, a more consistent experience is provided that matches industry standards while enabling more powerful validation capabilities through the ability to define sub-properties.
979+
980+
#### Alternatives for arrays
981+
982+
For arrays, you can replace `patternKey` and `patternValue` by using the `items` property with a subschema.
983+
984+
Example of replacing `patternValue` for an array of strings:
985+
986+
```json title="Old approach with patternValue"
987+
{
988+
"title": "Tags",
989+
"type": "array",
990+
"description": "Enter tags",
991+
"editor": "stringList",
992+
"patternValue": "^[a-zA-Z0-9-_]+$"
993+
}
994+
```
995+
996+
```json title="New approach with items subschema"
997+
{
998+
"title": "Tags",
999+
"type": "array",
1000+
"description": "Enter tags",
1001+
"editor": "stringList",
1002+
"items": {
1003+
"type": "string",
1004+
"pattern": "^[a-zA-Z0-9-_]+$"
1005+
}
1006+
}
1007+
```
1008+
1009+
Example of replacing both `patternKey` and `patternValue` for an array with key-value pairs:
1010+
1011+
```json title="Old approach with patternKey and patternValue"
1012+
{
1013+
"title": "Headers",
1014+
"type": "array",
1015+
"description": "HTTP headers",
1016+
"editor": "keyValue",
1017+
"patternKey": "^[a-zA-Z0-9-]+$",
1018+
"patternValue": "^.+$"
1019+
}
1020+
```
1021+
1022+
```json title="New approach with items subschema"
1023+
{
1024+
"title": "Headers",
1025+
"type": "array",
1026+
"description": "HTTP headers",
1027+
"editor": "keyValue",
1028+
"items": {
1029+
"type": "object",
1030+
"properties": {
1031+
"key": {
1032+
"title": "Name",
1033+
"type": "string",
1034+
"description": "Header name",
1035+
"pattern": "^[a-zA-Z0-9-]+$"
1036+
},
1037+
"value": {
1038+
"title": "Value",
1039+
"type": "string",
1040+
"description": "Header value",
1041+
"pattern": "^.+$"
1042+
}
1043+
},
1044+
"required": ["key", "value"]
1045+
}
1046+
}
1047+
```
1048+
1049+
#### Alternatives for objects
1050+
1051+
For objects, there is currently no direct replacement for `patternKey` and `patternValue` properties. These validation features will not be supported in future versions.
1052+
1053+
If you need to validate object properties, consider using a predefined schema with the `properties` field instead of allowing arbitrary properties with validation patterns.

0 commit comments

Comments
 (0)