• Analyze code first: Read the Actor's source to understand what data it actually pushes to the dataset — never guess
• Every field is nullable: APIs and websites are unpredictable — always set

  "nullable": true

• Anonymize examples: Never use real user IDs, usernames, or personal data in examples
• Verify against code: If TypeScript types exist, cross-check the schema against both the type definition AND the code that produces the values
• Reuse existing patterns: Before generating schemas, check if other Actors in the same repository already have output schemas — match their structure, naming conventions, description style, and formatting
• Don't reinvent the wheel: Reuse existing type definitions, interfaces, and utilities from the codebase instead of creating duplicate definitions

1. Create todo list with all phases
2. Find the

   .actor/

   directory containing

   actor.json

3. Read

   actor.json

   to understand the Actor's configuration
4. Check if

   dataset_schema.json

   ,

   output_schema.json

   , and

   key_value_store_schema.json

   already exist
5. Search for existing schemas in the repository: Look for other

   .actor/

   directories or schema files (e.g.,

   **/dataset_schema.json

   ,

   **/output_schema.json

   ,

   **/key_value_store_schema.json

   ) to learn the repo's conventions — match their description style, field naming, example formatting, and overall structure
6. Find all places where data is pushed to the dataset:
   • JavaScript/TypeScript: Search for

     Actor.pushData(

     ,

     dataset.pushData(

     ,

     Dataset.pushData(

   • Python: Search for

     Actor.push_data(

     ,

     dataset.push_data(

     ,

     Dataset.push_data(

7. Find all places where data is stored in the key-value store:
   • JavaScript/TypeScript: Search for

     Actor.setValue(

     ,

     keyValueStore.setValue(

     ,

     KeyValueStore.setValue(

   • Python: Search for

     Actor.set_value(

     ,

     key_value_store.set_value(

     ,

     KeyValueStore.set_value(

8. Find output type definitions — reuse them directly instead of recreating from scratch:
   • TypeScript: Look for output type interfaces/types (e.g., in

     src/types/

     ,

     src/types/output.ts

     ). If an interface or type already defines the output shape, derive the schema fields from it — do not create a parallel definition
   • Python: Look for TypedDict, dataclass, or Pydantic model definitions. Use the existing field names, types, and docstrings as the source of truth
9. Check for existing shared schema utilities or helper functions in the codebase that handle schema generation or validation — reuse them rather than creating new logic
10. If inline

    storages.dataset

    or

    storages.keyValueStore

    config exists in

    actor.json

    , note it for migration

• Match the description writing style (sentence case vs. lowercase, period vs. no period, etc.)
• Match the field naming convention (camelCase vs. snake_case) — this must also match the actual keys produced by the Actor code
• Match the example value style (e.g., date formats, URL patterns, placeholder names)
• Match the view structure (number of fields in overview, display format choices)
• Match the JSON formatting (indentation, property ordering, spacing) — all schemas in the same repository must use identical formatting, including standalone Actors

properties

fields.properties

properties

"nullable": true

"additionalProperties": true

fields

properties

"required": []

fields

properties

"type"

"nullable"

nullable

type

Warning — most common mistakes:

1. Only including fields that appear in the overview view. The

   fields.properties

   must list ALL output fields, even if they are not in the

   views

   section.
2. Only adding

   "required": []

   and

   "additionalProperties": true

   on nested object-type properties but forgetting them on the top-level

   fields

   object. Both levels need them.

Note:

nullable

is an Apify-specific extension to JSON Schema draft-07. It is intentional and correct.

• transformation.fields

  : List 8–12 most important field names (order = column order in UI)

• display.properties

  : One entry per overview field with

  label

  and

  format

• Available formats:

  "text"

  ,

  "number"

  ,

  "date"

  ,

  "link"

  ,

  "boolean"

  ,

  "image"

  ,

  "array"

  ,

  "object"

Skip this phase if no

Actor.setValue()

/

Actor.set_value()

calls were found in Phase 1 (beyond the default

INPUT

key).

setValue

set_value

1. Fixed keys (e.g.,

   "RESULTS"

   ,

   "summary"

   ) — use

   "key"

   (exact match)
2. Dynamic keys with a prefix (e.g.,

   "screenshot-${id}"

   ,

   f"image-{name}"

   ) — use

   "keyPrefix"

{
    "actorOutputSchemaVersion": 1,
    "title": "<Descriptive title — what the Actor returns>",
    "description": "<One sentence describing the output data>",
    "properties": {
        "dataset": {
            "type": "string",
            "title": "Results",
            "description": "Dataset containing all scraped data",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
        }
    }
}

Critical: Each property entry must include

"type": "string"

— this is an Apify-specific convention. The Apify meta-validator rejects properties without it (and rejects

"type": "object"

— only

"string"

is valid here).

key_value_store_schema.json

"files": {
    "type": "string",
    "title": "Files",
    "description": "Key-value store containing downloaded files",
    "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"
}

• {{links.apiDefaultDatasetUrl}}

  — API URL of default dataset

• {{links.apiDefaultKeyValueStoreUrl}}

  — API URL of default key-value store

• {{links.publicRunUrl}}

  — Public run URL

• {{links.consoleRunUrl}}

  — Console run URL

• {{links.apiRunUrl}}

  — API run URL

• {{links.containerRunUrl}}

  — URL of webserver running inside the run

• {{run.defaultDatasetId}}

  — ID of the default dataset

• {{run.defaultKeyValueStoreId}}

  — ID of the default key-value store

1. Read the current

   actor.json

2. Add or update the

   storages.dataset

   reference:
   json

   "storages": {
       "dataset": "./dataset_schema.json"
   }

3. If

   key_value_store_schema.json

   was generated, add the reference:
   json

   "storages": {
       "dataset": "./dataset_schema.json",
       "keyValueStore": "./key_value_store_schema.json"
   }

4. Add or update the

   output

   reference:
   json

   "output": "./output_schema.json"

5. If

   actor.json

   had inline

   storages.dataset

   or

   storages.keyValueStore

   objects (not string paths), migrate their content into the respective schema files and replace the inline objects with file path strings

• Every output field from the source code is in

  dataset_schema.json

  fields.properties

  — not just the overview view fields but ALL fields the Actor can produce
• Every field has

  "nullable": true

• The top-level

  fields

  object has both

  "additionalProperties": true

  and

  "required": []

• Every nested object within

  properties

  also has

  "additionalProperties": true

  and

  "required": []

• Every field has a

  "description"

  and an

  "example"

• All example values are anonymized

• "type"

  is present on every field that has

  "nullable"

• Views list 8–12 most useful fields with correct display formats

• output_schema.json

  has

  "type": "string"

  on every property
• If key-value store is used:

  key_value_store_schema.json

  has collections matching all

  setValue

  /

  set_value

  calls
• If key-value store is used: each collection uses either

  key

  or

  keyPrefix

  (not both)

• actor.json

  references all generated schema files
• Schema field names match the actual keys in the code (camelCase/snake_case consistency)
• If existing schemas were found in the repo, the new schema follows their conventions (description style, example format, view structure)
• Schema fields are derived from existing type definitions (interfaces, TypedDicts, dataclasses) where available — no duplicated or divergent field definitions

• Files created or updated
• Number of fields in the dataset schema
• Number of collections in the key-value store schema (if generated)
• Fields selected for the overview view
• Any fields that need user clarification (ambiguous types, unclear nullability)
• Suggested next steps (test locally with

  apify run

  , verify output tab in Console)