Output Schemas

1. Read .actor/actor.json. Note any existing schema files, and any inline storages.dataset or storages.keyValueStore objects (they migrate into files in step 5).
2. Search the repository for other .actor/*_schema.json files. Match their description style, field naming, example format, view size, and JSON formatting. A template’s dataset_schema.json with "fields": {} is a placeholder to replace, not a style to match.
3. Find every dataset write: pushData( in JS/TS, push_data( in Python.
4. Find every key-value store write: setValue( in JS/TS, set_value( in Python. Ignore the default INPUT key.
5. Find the output type: a TypeScript interface, or a Python TypedDict, dataclass, or Pydantic model. When one exists it is the canonical field list; derive the schema from it and cross-check against the code that fills the values.

Done when you can list every output field with its type, source location, and nullability, and every key-value store key pattern. Present that list to the user.

2. Write dataset_schema.json

fields.properties is the superset: every field the Actor can output. Views select a subset of it for display.

Rules for every field:

Two patterns cover the rest:

Arrays add "items": { "type": "string" }; enums add "enum": [...].

Views. transformation.fields lists the 8 to 12 fields a user wants at a glance, in column order. display.properties gives each one a label and a format from text, number, date, link, boolean, image, array, object. Transformation also accepts unwind, flatten, omit, limit, and desc.

3. Write key_value_store_schema.json (only when step 1 found store writes)

Group the writes by key pattern. A fixed key such as "REPORT" becomes a collection with key; a dynamic key such as `screenshot-${id}` becomes one with keyPrefix. Each collection uses exactly one of the two.

contentTypes restricts MIME types. jsonSchema (draft-07) validates application/json records.

4. Write output_schema.json

Every property has "type": "string"; the Apify meta-validator accepts no other type here. When step 3 produced a store schema, add a second property with template {{links.apiDefaultKeyValueStoreUrl}}/keys.

Available template variables: links.apiDefaultDatasetUrl, links.apiDefaultKeyValueStoreUrl, links.publicRunUrl, links.consoleRunUrl, links.apiRunUrl, links.containerRunUrl, run.defaultDatasetId, run.defaultKeyValueStoreId.

5. Wire actor.json

Include keyValueStore only when step 3 ran. Move any inline schema objects into the files and replace them with these path strings. When actor.json still has the deprecated input or output key, rename it to inputSchema or outputSchema.

6. Validate

Run apify validate-schema. It checks the structure of the input, dataset, and key-value store schemas, not the field rules below, and CLI 1.10 skips a schema referenced as outputSchema, so check output_schema.json against the list by hand. The work is done when every line holds:

• Not done: Every output field found in step 1 is in fields.properties.
• Not done: Every field has type, nullable: true, description, and an anonymized example.
• Not done: required: [] and additionalProperties: true sit on the top-level fields object and on every nested object.
• Not done: Field names match the keys the code writes (camelCase or snake_case as the code has them).
• Not done: The overview view lists 8 to 12 fields with correct formats.
• Not done: Every output_schema.json property has "type": "string".
• Not done: If a store schema exists, its collections cover every setValue / set_value call, each with key or keyPrefix but not both.
• Not done: actor.json references every schema file through inputSchema, outputSchema, and storages.
• Not done: apify validate-schema passes and reports the dataset and (if present) key-value store schemas, not only the input schema.
• Not done: Style matches the other schemas in the repository, and fields derive from the existing type definition when one exists.

Then show the user the schemas and report the files written, the field count, the overview fields, and any field whose type or nullability needs the user’s confirmation.