Skip to content

docs: fix Actor definition and storage schema inconsistencies #2868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TC-MO wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: fix Actor definition and storage schema inconsistencies #2868

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
48220db
docs: fix Actor definition and storage schema inconsistencies
TC-MO Aug 11, 2026
e24f2df
docs: clarify dataset alias naming rules
TC-MO Aug 11, 2026
09d139d
Apply suggestions from code review
TC-MO Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions sources/academy/platform/deploying_your_code/output_schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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)

Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
6 changes: 5 additions & 1 deletion sources/platform/actors/development/actor_definition/actor_json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -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"
Expand Down Expand Up @@ -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. |
Expand All @@ -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. |

@szaganek szaganek Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this :D we shouldn't use this without a noun

@TC-MO TC-MO Aug 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good point, I'll fix this one and the one I modeled it after on LOC89

@TC-MO TC-MO Aug 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:

Suggested change
| `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.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). |

And similar construction for the storages.dataset & storages.datasets

| 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 parth to a dataset schema file. Read about Actor dataset schemas. |
| 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. |

| `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. |
Expand Down
8 changes: 4 additions & 4 deletions sources/platform/actors/development/actor_definition/output_schema/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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"
}
```
Expand Down Expand Up @@ -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"
}
```
Expand Down Expand Up @@ -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"
}
```
Expand Down
8 changes: 5 additions & 3 deletions sources/platform/storage/dataset/dataset_schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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"
}
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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. |

Expand Down
5 changes: 4 additions & 1 deletion sources/platform/storage/dataset/multiple_datasets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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}` 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

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.

:::
Expand Down
6 changes: 3 additions & 3 deletions sources/platform/storage/key_value_store/key_value_store_schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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"
}
Expand Down Expand Up @@ -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,
Expand Down
Loading