Skip to content

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

Description

@DaveHanns

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._

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions