Problem
Users (and agents) who follow the academy tutorial sources/academy/tutorials/apify_scrapers/getting_started.md learn to create an INPUT_SCHEMA.json (or input_schema.json) file, but the tutorial never mentions the required .input reference in actor.json — the surrounding text (around lines 8, 18, and 20-27) teaches "create the schema file" in isolation.
The deprecation warning lives at input_schema/specification.md line 21, a page most getting-started readers won't visit:
Note: Placing INPUT_SCHEMA.json in the Actor's root is deprecated. Use .actor/INPUT_SCHEMA.json and reference it explicitly from actor.json.
As a result, agent-authored Actors ship a schema file without the actor.json linkage and continue to rely on filename-based auto-discovery, which is scheduled for removal.
Suggested change
Add a short section to the academy tutorial (right after the schema example) that teaches the two accepted forms:
### Reference the input schema from `actor.json`
Once you've written the schema file, reference it from `actor.json`:
**Form 1 — path reference (recommended):**
```json
{
"actorSpecification": 1,
"name": "my-actor",
"input": "./input_schema.json"
}
Form 2 — inline object:
{
"actorSpecification": 1,
"name": "my-actor",
"input": { /* schema contents */ }
}
Filename-based auto-discovery (dropping the .input field and hoping the platform finds INPUT_SCHEMA.json) is deprecated and will be removed in a future release. Always add the explicit .input reference.
Cross-reference the specification page for the full deprecation note.
## Related
- Companion PR against `apify/actor-templates` to add the same teaching to the `ts-empty` (and `js-empty`, `python-empty`) AGENTS.md Do-list.
- The overlay in the internal eval pack already teaches this — this issue closes the durable upstream side.
## Impact
Medium. Every agent-authored Actor that follows the academy tutorial ships without the `.input` reference. Forward-compatibility risk when Apify removes auto-discovery; also propagates the anti-pattern through every Actor those agents inspire.
---
_Surfaced during an evaluation of Apify surfaces for agent-driven Actor development._
Problem
Users (and agents) who follow the academy tutorial
sources/academy/tutorials/apify_scrapers/getting_started.mdlearn to create anINPUT_SCHEMA.json(orinput_schema.json) file, but the tutorial never mentions the required.inputreference inactor.json— the surrounding text (around lines 8, 18, and 20-27) teaches "create the schema file" in isolation.The deprecation warning lives at
input_schema/specification.mdline 21, a page most getting-started readers won't visit:As a result, agent-authored Actors ship a schema file without the
actor.jsonlinkage and continue to rely on filename-based auto-discovery, which is scheduled for removal.Suggested change
Add a short section to the academy tutorial (right after the schema example) that teaches the two accepted forms:
Form 2 — inline object:
{ "actorSpecification": 1, "name": "my-actor", "input": { /* schema contents */ } }Filename-based auto-discovery (dropping the
.inputfield and hoping the platform findsINPUT_SCHEMA.json) is deprecated and will be removed in a future release. Always add the explicit.inputreference.