Skip to content

docs: Update input schema specs #1307

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

Merged
merged 5 commits into from
Nov 28, 2024
Merged

docs: Update input schema specs #1307

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
90416b6
Update specification.md
jancurn Nov 27, 2024
d74d7e5
Update sources/platform/actors/development/actor_definition/input_sch…
jancurn Nov 27, 2024
a86fc15
Update specification.md
jancurn Nov 28, 2024
3c31b98
Update sources/platform/actors/development/actor_definition/input_sch…
jancurn Nov 28, 2024
65b342f
Update specification.md
jancurn Nov 28, 2024
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
13 changes: 5 additions & 8 deletions sources/platform/actors/development/actor_definition/input_schema/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,20 +11,17 @@

---

The input schema serves two primary purposes for an Actor:
The Actor input schema serves two primary purposes:

- It defines the structure and validation rules for the input data the Actor accepts.
- It determines the user interface components rendered in the Apify Console for configuring the Actor's input.

By defining an input schema, you can provide a user-friendly interface for configuring your Actor while ensuring that the input data supplied by users adheres to the specified requirements and constraints.
By defining an input schema, you can provide a user-friendly interface for configuring your Actor while ensuring that the input data supplied by users adheres to the specified requirements and constraints. Also, the input schema make it easy to call and integrate your Actor from external systems.

You can specify input schema for an Actor in multiple ways:
To define an input schema for an Actor, set `input` field in the `.actor/actor.json` file to an input schema object as described below, or path to a JSON file containing the input schema.
For backwards compability, if the `input` field is omitted, the system looks for an `INPUT_SCHEMA.json` file in the `.actor` directory or for an `INPUT_SCHEMA.json` file in the Actor's root directory - but do not depend on this behavior as it might be removed in the future.

Check warning on line 22 in sources/platform/actors/development/actor_definition/input_schema/specification.md

View workflow job for this annotation

GitHub Actions / Spell Check with Typos 

"compability" should be "compatibility".
Copy link
Contributor

@TC-MO TC-MO Nov 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Suggested change
To define an input schema for an Actor, set `input` field in the `.actor/actor.json` file to an input schema object as described below, or path to a JSON file containing the input schema.
For backwards compability, if the `input` field is omitted, the system looks for an `INPUT_SCHEMA.json` file in the `.actor` directory or for an `INPUT_SCHEMA.json` file in the Actor's root directory - but do not depend on this behavior as it might be removed in the future.
To define an input schema for an Actor, set `input` field in the `.actor/actor.json` file to an input schema object as described below, or path to a JSON file containing the input schema.
For backwards compatibility, if the `input` field is omitted, the system checks these locations:
1. `INPUT_SCHEMA.json` in the `.actor` directory
2. `INPUT_SCHEMA.json` in the Actor's root directory

I would omit any information about what might or might not happen, if it does then we can update the documentation with a note. If we want to steer users in one direction we can add that some info about preferred or recommended way of doing things

Copy link
Member Author

@jancurn jancurn Nov 27, 2024

Choose a reason for hiding this comment

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

IMO it's quite normal in docs to say that some behavior might be deprecetated in the future, so that people don't use it - this is exactly the case

Copy link
Contributor

@TC-MO TC-MO Nov 27, 2024

Choose a reason for hiding this comment

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

In my experience with docuemntation, I've never seen a message with possibility of depreacation. It was always with specific end-of-life dates.

If we want to guide users towards a preferred implementation I would advise to explicitly mention which way is recommended.

Copy link
Member Author

@jancurn jancurn Nov 27, 2024

Choose a reason for hiding this comment

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

Really? I see it all the time in docs that some feature is deprecated and might be removed in the future. See https://www.google.com/search?q=deprecated+and+might+be+removed+in+the+future

Copy link
Contributor

@TC-MO TC-MO Nov 27, 2024

Choose a reason for hiding this comment

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

But none of the results are from official documentation but rather community resources.

Furthermore
deprecated & might be removed in the future =/= might be removed in the future,
if the intention is that these two ways of defining input schema are deprecated and & will be removed in the future, then let's mark them explicitly as deprecated and then mentioning that they might be removed in the future is a-ok

Copy link
Member Author

@jancurn jancurn Nov 27, 2024

Choose a reason for hiding this comment

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

Oh right, fair enough, I'll mention it's deprecated


- One approach embeds it as an object within the `.actor/actor.json` file under the `input` field or provide a path to a `JSON` file containing the input schema in the same `input` field.
- If you omit the `input` field in the `.actor/actor.json` file, the system will look for an `INPUT_SCHEMA.json` file in the `.actor` directory.
- In the absence of that file, it will search for an `INPUT_SCHEMA.json` file in the Actor's root directory.

The max allowed size for the input schema file is 500 kB. When you provide an input schema, the system will validate the input data passed to the Actor during execution (via the API or the Apify Console) against the specified schema to ensure compliance before starting the Actor.
The maximum allowed size for the input schema file is 500 kB. When you provide an input schema, the system will validate the input data passed to the Actor during execution (via the API or the Apify Console) against the specified schema to ensure compliance before starting the Actor.

:::note Validation aid

Expand Down
Loading