Skip to content

fix: correct actor.json version examples and clarify input schema linkage #2662

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

Draft
DaveHanns wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

fix: correct actor.json version examples and clarify input schema linkage #2662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
48 changes: 48 additions & 0 deletions sources/academy/platform/deploying_your_code/input_schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,54 @@

For our case, we've made the **numbers** field required, as it is crucial to our Actor's run.

## Reference the schema in actor.json {#reference-in-actor-json}

Once you've created your `input_schema.json` file, you need to reference it from your Actor's configuration file `.actor/actor.json`. You have two options.

### Option 1: Path reference (recommended)

In `.actor/actor.json`, add the `input` field pointing to your schema file:

```json title=".actor/actor.json"
{
"actorSpecification": 1,
"name": "my-actor",
"version": "1.0",
"input": "./input_schema.json"
}
```

### Option 2: Inline schema

Alternatively, you can embed the entire input schema directly in `actor.json`:

```json title=".actor/actor.json"
{
"actorSpecification": 1,
"name": "my-actor",
"version": "1.0",
"input": {
"title": "Adding Actor input",
"type": "object",
"schemaVersion": 1,
"properties": {
"numbers": {
"title": "Number list",
"type": "array",
"editor": "json"
}
},
"required": ["numbers"]
}
}
```

:::note Auto-discovery is deprecated

For backwards compatibility, if the `input` field is omitted, the system looks for an `INPUT_SCHEMA.json` file either in the `.actor` directory or the Actor's top-level directory — but note that this functionality is deprecated and might be removed in the future. Always explicitly reference your input schema in `actor.json` via the `input` field to ensure forward compatibility.

Check failure on line 151 in sources/academy/platform/deploying_your_code/input_schema.md

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "sources/academy/platform/deploying_your_code/input_schema.md", "range": {"start": {"line": 151, "column": 179}}}, "severity": "ERROR"}

:::

## Final thoughts {#final-thoughts}

Here is what the input schema we wrote will render on the platform:
Expand Down
2 changes: 1 addition & 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 @@ -80,7 +80,7 @@
| `dockerfile` | Optional | The path to the Dockerfile to be used for building the Actor on the platform. If not specified, the system will search for Dockerfiles in the `.actor/Dockerfile` and `Dockerfile` paths, in that order. Refer to the [Dockerfile](./docker.md) section for more information. |
| `dockerContextDir` | Optional | The path to the directory to be used as the Docker context when building the Actor. The path is relative to the location of the `actor.json` file. This property is useful for monorepos containing multiple Actors. Refer to the [Actor monorepos](../deployment/source_types.md#actor-monorepos) section for more details. |
| `readme` | Optional | The path to the README file to be used on the platform. If not specified, the system will look for README files in the `.actor/README.md` and `README.md` paths, in that order of preference. Check out [Apify Marketing Playbook to learn how to write a quality README files](https://apify.notion.site/How-to-create-an-Actor-README-759a1614daa54bee834ee39fe4d98bc2) guidance. |
| `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. |
| `input` | Optional | Specify your [input schema](./input_schema/index.md) either as a path to a JSON file (e.g., `"./input_schema.json"`) or as an embedded object directly in `actor.json`. **Always explicitly reference your input schema in the `input` field.** For backwards compatibility, if not provided, the system looks for `INPUT_SCHEMA.json` in the `.actor` or root directory — but note that this auto-discovery functionality is deprecated and might be removed in the future. You can also use the `inputSchema` alias interchangeably. |

Check failure on line 83 in sources/platform/actors/development/actor_definition/actor_json.md

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "sources/platform/actors/development/actor_definition/actor_json.md", "range": {"start": {"line": 83, "column": 384}}}, "severity": "ERROR"}
| `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](/platform/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](/platform/actors/development/actor-definition/dataset-schema) about Actor dataset schemas. |
Expand Down
12 changes: 9 additions & 3 deletions sources/platform/actors/development/actor_definition/dataset_schema/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@ sidebar_label: Dataset schema

The dataset schema defines the structure and presentation of data produced by an Actor. It controls what fields each dataset item contains and how that data appears in the Output tab.

:::warning Version format requirement

Apify's platform requires the `actor.json` `version` field in `MAJOR.MINOR` format (e.g., `1.0`, `0.1`, `2.3`), where each segment is a number from 0–99. Three-part semantic versions like `1.0.0` are rejected by the platform. See the [actor.json reference](../actor_json.md) for details.

:::

## Schema components

A dataset schema has two components:
Expand Down Expand Up @@ -46,7 +52,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 +76,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 +157,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
Loading