From 48220dbe4715af75304ac82b7742f04a4f42ab58 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 11 Aug 2026 19:50:40 +0200 Subject: [PATCH 1/5] docs: fix Actor definition and storage schema inconsistencies --- .../academy/platform/deploying_your_code/output_schema.md | 6 +++--- .../actors/development/actor_definition/actor_json.md | 6 +++++- .../development/actor_definition/output_schema/index.md | 8 ++++---- sources/platform/storage/dataset/dataset_schema.md | 8 +++++--- sources/platform/storage/dataset/multiple_datasets.mdx | 2 +- .../storage/key_value_store/key_value_store_schema.md | 6 +++--- 6 files changed, 21 insertions(+), 15 deletions(-) diff --git a/sources/academy/platform/deploying_your_code/output_schema.md b/sources/academy/platform/deploying_your_code/output_schema.md index b02d492061..725c3e964d 100644 --- a/sources/academy/platform/deploying_your_code/output_schema.md +++ b/sources/academy/platform/deploying_your_code/output_schema.md @@ -17,7 +17,7 @@ In this quick tutorial, you will learn how to set up an output tab for your own ## Implementation -Firstly, create a `.actor` folder in the root of your Actor's source code. Then, create a `actor.json` file in this folder, after which you'll have .actor/actor.json. +First, create a `.actor` folder in the root of your Actor's source code. Then, create an `actor.json` file in this folder, after which you'll have `.actor/actor.json`. ![.actor/actor.json](./images/actor-json-example.webp) @@ -28,7 +28,7 @@ Next, copy-paste the following template code into your `actor.json` file. "actorSpecification": 1, "name": "___ENTER_ACTOR_NAME____", "title": "___ENTER_ACTOR_TITLE____", - "version": "1.0.0", + "version": "1.0", "storages": { "dataset": { "actorSpecification": 1, @@ -77,7 +77,7 @@ For reference, you can use the [Zappos Scraper source code](https://github.com/P "name": "zappos-scraper", "title": "Zappos Scraper", "description": "", - "version": "1.0.0", + "version": "1.0", "storages": { "dataset": { "actorSpecification": 1, diff --git a/sources/platform/actors/development/actor_definition/actor_json.md b/sources/platform/actors/development/actor_definition/actor_json.md index b9e13e0e89..6c932a9c6f 100644 --- a/sources/platform/actors/development/actor_definition/actor_json.md +++ b/sources/platform/actors/development/actor_definition/actor_json.md @@ -21,6 +21,7 @@ import TabItem from '@theme/TabItem'; "actorSpecification": 1, // always 1 "name": "name-of-my-scraper", "title": "My Web Scraper", + "description": "Extract data from example.com.", "version": "0.0", "buildTag": "latest", "meta": { @@ -39,7 +40,8 @@ import TabItem from '@theme/TabItem'; "input": "./input_schema.json", "output": "./output_schema.json", "storages": { - "dataset": "./dataset_schema.json" + "dataset": "./dataset_schema.json", + "keyValueStore": "./key_value_store_schema.json" }, "webServerSchema": "./web_server_openapi.json", "webServerMcpPath": "/mcp" @@ -73,6 +75,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `actorSpecification` | Required | The version of the Actor specification. This property must be set to `1`, which is the only version available. | | `name` | Required | The name of the Actor. | | `title` | Optional | The display title of the Actor. This is the human-readable title shown in Apify Console and Apify Store. If not specified, the `name` property is used as the title. | +| `description` | Optional | The description of the Actor. | | `version` | Required | The version of the Actor, specified in the format `[Number].[Number]`, e.g., `0.1`, `0.3`, `1.0`, `1.3`, etc. | | `buildTag` | Optional | The tag name to be applied to a successful build of the Actor. If not specified, defaults to `latest`. Refer to the [builds](../builds_and_runs/builds.md) for more information. | | `meta` | Optional | Metadata object containing additional information about the Actor. Currently supports `templateId` field to identify the template from which the Actor was created. | @@ -85,6 +88,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `changelog` | Optional | The path to the CHANGELOG file displayed in the Information tab of the Actor in Apify Console next to Readme. If not provided, the CHANGELOG at `.actor/CHANGELOG.md` or `CHANGELOG.md` is used, in this order of preference. Your Actor doesn't need to have a CHANGELOG but it is a good practice to keep it updated for published Actors. | | `storages.dataset` | Optional | You can define the schema of the items in your dataset under the `storages.dataset` field. This can be either an embedded object or a path to a JSON schema file. [Read more](/storage/dataset-schema) about Actor dataset schemas. | | `storages.datasets` | Optional | You can define multiple datasets for the Actor under the `storages.datasets` field. This can be an object containing embedded objects or paths to a JSON schema files. [Read more](/storage/dataset-schema/multiple-datasets) about multiple dataset schemas. | +| `storages.keyValueStore` | Optional | You can define key-value store collections under the `storages.keyValueStore` field. This can be either an embedded object or a path to a key-value store schema file. [Read more](/storage/key-value-store-schema) about Actor key-value store schemas. | | `defaultMemoryMbytes` | Optional | Specifies the default amount of memory in megabytes to be used when the Actor is started. Can be an integer or a [dynamic memory expression string](./dynamic_actor_memory/index.md). | | `minMemoryMbytes` | Optional | Specifies the minimum amount of memory in megabytes required by the Actor to run. Requires an _integer_ value. If both `minMemoryMbytes` and `maxMemoryMbytes` are set, then `minMemoryMbytes` must be equal or lower than `maxMemoryMbytes`. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `maxMemoryMbytes` | Optional | Specifies the maximum amount of memory in megabytes required by the Actor to run. It can be used to control the costs of run. Requires an _integer_ value. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | diff --git a/sources/platform/actors/development/actor_definition/output_schema/index.md b/sources/platform/actors/development/actor_definition/output_schema/index.md index a5c6b6971b..6154c42704 100644 --- a/sources/platform/actors/development/actor_definition/output_schema/index.md +++ b/sources/platform/actors/development/actor_definition/output_schema/index.md @@ -35,7 +35,7 @@ You can organize the files using one of these structures: "actorSpecification": 1, "name": "files-scraper", "title": "Files scraper", - "version": "1.0.0", + "version": "1.0", "output": { "actorOutputSchemaVersion": 1, "title": "Output schema of the files scraper", @@ -51,7 +51,7 @@ You can organize the files using one of these structures: "actorSpecification": 1, "name": "files-scraper", "title": "Files scraper", - "version": "1.0.0", + "version": "1.0", "output": "./output_schema.json" } ``` @@ -149,7 +149,7 @@ To specify that the Actor is using output schema, update the `.actor/actor.json` "actorSpecification": 1, "name": "Actor Name", "title": "Actor Title", - "version": "1.0.0", + "version": "1.0", "output": "./output_schema.json" } ``` @@ -216,7 +216,7 @@ To specify that the Actor is using output schema, update the `.actor/actor.json` "actorSpecification": 1, "name": "Actor Name", "title": "Actor Title", - "version": "1.0.0", + "version": "1.0", "output": "./output_schema.json" } ``` diff --git a/sources/platform/storage/dataset/dataset_schema.md b/sources/platform/storage/dataset/dataset_schema.md index 811fb2653a..668e169de6 100644 --- a/sources/platform/storage/dataset/dataset_schema.md +++ b/sources/platform/storage/dataset/dataset_schema.md @@ -46,7 +46,7 @@ Place the dataset schema in the `.actor` folder in your Actor's root directory. "actorSpecification": 1, "name": "my-scraper", "title": "My Scraper", - "version": "1.0.0", + "version": "1.0", "storages": { "dataset": { "actorSpecification": 1, @@ -70,7 +70,7 @@ Place the dataset schema in the `.actor` folder in your Actor's root directory. "actorSpecification": 1, "name": "my-scraper", "title": "My Scraper", - "version": "1.0.0", + "version": "1.0", "storages": { "dataset": "./dataset_schema.json" } @@ -151,7 +151,7 @@ Configure the Output tab with a dataset schema: "actorSpecification": 1, "name": "Actor Name", "title": "Actor Title", - "version": "1.0.0", + "version": "1.0", "storages": { "dataset": { "actorSpecification": 1, @@ -418,6 +418,8 @@ Alternatively, flatten nested structures in your Actor code before calling `Acto | Property | Type | Required | Description | | --- | --- | --- | --- | | `actorSpecification` | integer | true | Version of the dataset schema structure. Only version 1 is available. | +| `title` | string | false | Title of the dataset schema. | +| `description` | string | false | Description of the dataset schema. | | `fields` | JSONSchema object | false | Schema of one dataset object using JSON Schema Draft 2020-12 or compatible format. | | `views` | Object | true | An object containing view definitions. Each key is a view ID, each value is a DatasetView object. | diff --git a/sources/platform/storage/dataset/multiple_datasets.mdx b/sources/platform/storage/dataset/multiple_datasets.mdx index 5746f868e7..071978557c 100644 --- a/sources/platform/storage/dataset/multiple_datasets.mdx +++ b/sources/platform/storage/dataset/multiple_datasets.mdx @@ -25,7 +25,7 @@ Define datasets in your Actor schema using the `datasets` object: "actorSpecification": 1, "name": "my-e-commerce-scraper", "title": "E-Commerce Scraper", - "version": "1.0.0", + "version": "1.0", "storages": { "datasets": { "default": "./products_dataset_schema.json", diff --git a/sources/platform/storage/key_value_store/key_value_store_schema.md b/sources/platform/storage/key_value_store/key_value_store_schema.md index 4c07bcf2f3..520a87e78a 100644 --- a/sources/platform/storage/key_value_store/key_value_store_schema.md +++ b/sources/platform/storage/key_value_store/key_value_store_schema.md @@ -38,7 +38,7 @@ Place the key-value store schema in the `.actor` folder in your Actor's root dir "actorSpecification": 1, "name": "this-is-book-library-scraper", "title": "Book Library scraper", - "version": "1.0.0", + "version": "1.0", "storages": { "keyValueStore": { "actorKeyValueStoreSchemaVersion": 1, @@ -56,7 +56,7 @@ Place the key-value store schema in the `.actor` folder in your Actor's root dir "actorSpecification": 1, "name": "this-is-book-library-scraper", "title": "Book Library scraper", - "version": "1.0.0", + "version": "1.0", "storages": { "keyValueStore": "./key_value_store_schema.json" } @@ -123,7 +123,7 @@ To organize those records, define collections in the `.actor/actor.json` configu "actorSpecification": 1, "name": "Actor Name", "title": "Actor Title", - "version": "1.0.0", + "version": "1.0", "storages": { "keyValueStore": { "actorKeyValueStoreSchemaVersion": 1, From e24f2dfa38bd3d18e7150d3305f46f9821286421 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 11 Aug 2026 20:08:49 +0200 Subject: [PATCH 2/5] docs: clarify dataset alias naming rules --- sources/platform/storage/dataset/multiple_datasets.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sources/platform/storage/dataset/multiple_datasets.mdx b/sources/platform/storage/dataset/multiple_datasets.mdx index 071978557c..13f792977c 100644 --- a/sources/platform/storage/dataset/multiple_datasets.mdx +++ b/sources/platform/storage/dataset/multiple_datasets.mdx @@ -42,12 +42,15 @@ The keys of the `datasets` object are aliases that refer to specific datasets. T Requirements: - The `datasets` object must contain the `default` alias +- Dataset aliases must match `[A-Za-z][A-Za-z0-9_]{0,100}`. Start each alias with a letter and use only letters, numbers, and underscores. Hyphens aren't supported. - The `datasets` and `dataset` objects are mutually exclusive (use one or the other) :::info Alias versus named dataset On the Apify platform, aliases and names behave differently. Named datasets are persistent. The automatic data retention policy doesn't apply to them. Aliased datasets follow the data retention of their run, and aliases only have meaning within a specific run. +Alias naming rules are stricter than named dataset naming rules. For example, `Actor.openDataset('my-new-dataset')` creates a named dataset and accepts hyphens, but `my-new-dataset` isn't a valid `storages.datasets` alias. Use `my_new_dataset` instead. + Behavior differs when an SDK runs outside the platform. See the SDK notes below. ::: From 09d139d14256877582ca0ed508bb94375654f033 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 12 Aug 2026 15:03:15 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Edyta <142720610+szaganek@users.noreply.github.com> --- sources/academy/platform/deploying_your_code/output_schema.md | 2 +- sources/platform/storage/dataset/multiple_datasets.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/academy/platform/deploying_your_code/output_schema.md b/sources/academy/platform/deploying_your_code/output_schema.md index 725c3e964d..a4d4696c80 100644 --- a/sources/academy/platform/deploying_your_code/output_schema.md +++ b/sources/academy/platform/deploying_your_code/output_schema.md @@ -17,7 +17,7 @@ In this quick tutorial, you will learn how to set up an output tab for your own ## Implementation -First, create a `.actor` folder in the root of your Actor's source code. Then, create an `actor.json` file in this folder, after which you'll have `.actor/actor.json`. +First, create an `.actor` folder in the root of your Actor's source code. Then, create an `actor.json` file in this folder, after which you'll have `.actor/actor.json`. ![.actor/actor.json](./images/actor-json-example.webp) diff --git a/sources/platform/storage/dataset/multiple_datasets.mdx b/sources/platform/storage/dataset/multiple_datasets.mdx index 13f792977c..7f4327d910 100644 --- a/sources/platform/storage/dataset/multiple_datasets.mdx +++ b/sources/platform/storage/dataset/multiple_datasets.mdx @@ -42,7 +42,7 @@ The keys of the `datasets` object are aliases that refer to specific datasets. T Requirements: - The `datasets` object must contain the `default` alias -- Dataset aliases must match `[A-Za-z][A-Za-z0-9_]{0,100}`. Start each alias with a letter and use only letters, numbers, and underscores. Hyphens aren't supported. +- Dataset aliases must match `[A-Za-z][A-Za-z0-9_]{0,100}` and start with a letter. Use letters, numbers, and underscores. Hyphens aren't supported. - The `datasets` and `dataset` objects are mutually exclusive (use one or the other) :::info Alias versus named dataset From fb66a21869464d5a337c8b7e6970a8232851def5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:35:29 +0200 Subject: [PATCH 4/5] docs: name the subject in actor.json storages descriptions Replace the bare demonstrative 'This can be either...' in the storages.dataset, storages.datasets, and storages.keyValueStore rows, per review feedback. Also fixes 'paths to a JSON schema files' and swaps 'Read more' for descriptive link text. --- .../actors/development/actor_definition/actor_json.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/actor_json.md b/sources/platform/actors/development/actor_definition/actor_json.md index 6c932a9c6f..60e6d2bdd2 100644 --- a/sources/platform/actors/development/actor_definition/actor_json.md +++ b/sources/platform/actors/development/actor_definition/actor_json.md @@ -86,9 +86,9 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `input` | Optional | You can embed your [input schema](./input_schema/index.md) object directly in `actor.json` under the `input` field. You can also provide a path to a custom input schema. If not provided, the input schema at `.actor/INPUT_SCHEMA.json` or `INPUT_SCHEMA.json` is used, in this order of preference. You can also use the `inputSchema` alias interchangeably. | | `output` | Optional | You can embed your [output schema](./output_schema/index.md) object directly in `actor.json` under the `output` field. You can also provide a path to a custom output schema. [Read more](/actors/development/actor-definition/output-schema) about Actor output schemas. You can also use the `outputSchema` alias interchangeably. | | `changelog` | Optional | The path to the CHANGELOG file displayed in the Information tab of the Actor in Apify Console next to Readme. If not provided, the CHANGELOG at `.actor/CHANGELOG.md` or `CHANGELOG.md` is used, in this order of preference. Your Actor doesn't need to have a CHANGELOG but it is a good practice to keep it updated for published Actors. | -| `storages.dataset` | Optional | You can define the schema of the items in your dataset under the `storages.dataset` field. This can be either an embedded object or a path to a JSON schema file. [Read more](/storage/dataset-schema) about Actor dataset schemas. | -| `storages.datasets` | Optional | You can define multiple datasets for the Actor under the `storages.datasets` field. This can be an object containing embedded objects or paths to a JSON schema files. [Read more](/storage/dataset-schema/multiple-datasets) about multiple dataset schemas. | -| `storages.keyValueStore` | Optional | You can define key-value store collections under the `storages.keyValueStore` field. This can be either an embedded object or a path to a key-value store schema file. [Read more](/storage/key-value-store-schema) about Actor key-value store schemas. | +| `storages.dataset` | Optional | The `storages.dataset` property defines the schema for the Actor's default dataset. Set the property to an embedded dataset schema object or a path to a dataset schema file. [Read about Actor dataset schemas](/storage/dataset-schema). | +| `storages.datasets` | Optional | The `storages.datasets` property defines multiple datasets for the Actor. Set the property to an object that maps dataset aliases to embedded dataset schema objects or paths to dataset schema files. [Read about multiple dataset schemas](/storage/dataset-schema/multiple-datasets). | +| `storages.keyValueStore` | Optional | The `storages.keyValueStore` property defines the schema for the Actor's default key-value store. Set the property to an embedded key-value store schema object or a path to a key-value store schema file. [Read about Actor key-value store schemas](/storage/key-value-store-schema). | | `defaultMemoryMbytes` | Optional | Specifies the default amount of memory in megabytes to be used when the Actor is started. Can be an integer or a [dynamic memory expression string](./dynamic_actor_memory/index.md). | | `minMemoryMbytes` | Optional | Specifies the minimum amount of memory in megabytes required by the Actor to run. Requires an _integer_ value. If both `minMemoryMbytes` and `maxMemoryMbytes` are set, then `minMemoryMbytes` must be equal or lower than `maxMemoryMbytes`. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `maxMemoryMbytes` | Optional | Specifies the maximum amount of memory in megabytes required by the Actor to run. It can be used to control the costs of run. Requires an _integer_ value. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | From 96d4156baf8a084fae4c330df468e010caef8043 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:37:46 +0200 Subject: [PATCH 5/5] docs: apply the same frame to the title and webServerSchema rows Extends the parallel 'The `X` property defines... Set the property to...' construction to the two remaining rows carrying a bare demonstrative, so all five rewritten descriptions share one shape. --- .../actors/development/actor_definition/actor_json.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/actor_json.md b/sources/platform/actors/development/actor_definition/actor_json.md index 60e6d2bdd2..17ce38afeb 100644 --- a/sources/platform/actors/development/actor_definition/actor_json.md +++ b/sources/platform/actors/development/actor_definition/actor_json.md @@ -74,7 +74,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | --- | --- | --- | | `actorSpecification` | Required | The version of the Actor specification. This property must be set to `1`, which is the only version available. | | `name` | Required | The name of the Actor. | -| `title` | Optional | The display title of the Actor. This is the human-readable title shown in Apify Console and Apify Store. If not specified, the `name` property is used as the title. | +| `title` | Optional | The `title` property defines the human-readable display title of the Actor, shown in Apify Console and Apify Store. If not specified, the `name` property is used as the title. | | `description` | Optional | The description of the Actor. | | `version` | Required | The version of the Actor, specified in the format `[Number].[Number]`, e.g., `0.1`, `0.3`, `1.0`, `1.3`, etc. | | `buildTag` | Optional | The tag name to be applied to a successful build of the Actor. If not specified, defaults to `latest`. Refer to the [builds](../builds_and_runs/builds.md) for more information. | @@ -93,5 +93,5 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `minMemoryMbytes` | Optional | Specifies the minimum amount of memory in megabytes required by the Actor to run. Requires an _integer_ value. If both `minMemoryMbytes` and `maxMemoryMbytes` are set, then `minMemoryMbytes` must be equal or lower than `maxMemoryMbytes`. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `maxMemoryMbytes` | Optional | Specifies the maximum amount of memory in megabytes required by the Actor to run. It can be used to control the costs of run. Requires an _integer_ value. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `usesStandbyMode` | Optional | Boolean specifying whether the Actor will have [Standby mode](../programming_interface/actor_standby.md) enabled. | -| `webServerSchema` | Optional | Defines an OpenAPI v3 schema for the web server running in the Actor. This can be either an embedded object or a path to a JSON schema file. Use this when your Actor starts its own HTTP server and you want to describe its interface. | +| `webServerSchema` | Optional | The `webServerSchema` property defines an OpenAPI v3 schema for the web server running in the Actor. Set the property to an embedded OpenAPI schema object or a path to a JSON schema file. Define the schema when your Actor starts its own HTTP server and you want to describe its interface. | | `webServerMcpPath` | Optional | The HTTP endpoint path where the Actor exposes its MCP (Model Context Protocol) server functionality. When set, the Actor is recognized as an MCP server. For example, setting `"/mcp"` designates the `/mcp` endpoint as the MCP interface. This path becomes part of the Actor's stable URL when [Standby mode](../programming_interface/actor_standby.md) is enabled. |