docs(academy): teach explicit .input reference in actor.json; auto-discovery is deprecated

Open Beginner friendly
  • Is something wrong?
#2,741 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@honzajavorek is already working on this.

Since Nov 4, 2026.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Domain
documentation

Research direction

Read sources/academy/tutorials/apify_scrapers/getting_started.md, especially the schema example and surrounding instructions around lines 8, 18, and 20-27. Add the suggested section explaining both .input forms and link to the input-schema specification page; done when the tutorial teaches explicit linkage and warns that filename-based auto-discovery is deprecated.

Written by the indexing model from the issue text.

Description

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._
Dominant language
JavaScript
Stars
82
Forks
240
Avg merge
3d 17h
Merged PRs (30d)
73

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from apify/apify-docs

All issues in apify/apify-docs

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.