Optimizing your input schema. Learn to design and refine your input schema with best practices for a better user experience.
So you've succeeded: your user has 1. found your Actor on Google, 2. explored the Actor's landing page, 3. decided to try it, and 4. created an Apify account. Now they’re on your Actor's page in the Console. The SEO fight is over. What’s next?
Your user is finally one-on-one with your Actor — specifically, its input schema. This is the moment when they try your Actor and decide whether to stick with it. The input schema is your middleman here, and you want it to work in your favor.
Technically, the input schema is a JSON object with various field types supported by the Apify platform, designed to simplify the use of the Actor. Based on the input schema you define, the Apify platform automatically generates a user interface for your Actor.
Of course, you can create an Actor without setting up an elaborate input schema. If your Actor is designed for users who don't need a good interface (e.g., they’ll use a JSON object and call it via API), you can skip this guide. But most users engage with Actors in Manual mode, aka the Actor interface. So, if your Actor is complex or you’re targeting regular users who need an intuitive interface, it's essential to consider their experience.
In this article, we’ll refer to the input schema as the user interface of your Actor and focus exclusively on it.
<aside> ❗ To fully understand the recommendations in this blog post, you’ll first need to familiarize yourself with the technical aspects of the input schema. This context is crucial to make good use of the insights shared here.
</aside>
When facing the Apify platform for the first time, it can feel intimidating. You only have a few seconds for the user to assess the ease of using your Actor.
If something goes wrong or is unclear with the input, an ideal user will first turn to the tooltips in the input schema. Next, they might check the README or tutorials, and finally, they’ll reach out to you through the Issues tab. However, many users won’t go through all these steps — they may simply get overwhelmed and abandon the tool altogether.
A well-designed input schema is all about managing user expectations, reducing cognitive load, and preventing frustration. All that is done by educating your user. Ideally, a good input schema, as your first line of interaction, should: