docs: restructure dataset schema page with introduction and guidance by jancurn · Pull Request #2554 · apify/apify-docs

jancurn · 2026-05-21T10:06:54Z

Summary

Restructures the dataset schema documentation to provide proper context before diving into details:

Adds introduction explaining what dataset schema is and its two components (fields and views)
Moves file structure section before examples so readers know where to put code
Reorganizes content into clear Fields and Views sections as parallel concepts
Adds guidance on why/when to use views (addressing user feedback)
Documents what views are NOT for (anti-patterns, export format misconceptions)
Adds multi-view example for different use cases (Marketing vs Pricing)
Consolidates reference tables at the end
Links to Google Maps Scraper as real-world example

The page now follows the same pattern as other actor definition pages (input_schema, output_schema).

Context

Based on feedback from Martin Sabo and Jaroslav Hejlek in #dev-docs - the documentation explained HOW to configure views but not WHY or WHEN to use them.

Slack thread: https://apify.slack.com/archives/C010Q0FBYG3/p1779357816377359?thread_ts=1779115904.940779&cid=C010Q0FBYG3

Test plan

Verify page renders correctly in preview
Check all code examples are valid JSON
Verify Google Maps Scraper link works
Confirm new headings appear in table of contents

https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

Adds a comprehensive "Why use views" section to dataset schema docs that explains the purpose and benefits of views, when to use them, how to organize views by use case, and what views are NOT for. Also includes a practical multi-view example for an e-commerce scraper. This addresses feedback that the documentation explained HOW to configure views but not WHY or WHEN to use them. Slack thread: https://apify.slack.com/archives/C010Q0FBYG3/p1779357816377359?thread_ts=1779115904.940779&cid=C010Q0FBYG3 https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

apify-service-account · 2026-05-21T10:07:27Z

✅ Preview for this PR (commit 140028ab) is ready at https://pr-2554.preview.docs.apify.com (see action run).

- Shorten the why/when content significantly - Add link to Google Maps Scraper as real-world example - Keep the anti-pattern note (useful guidance) - Remove redundant explanations https://claude.ai/code/session_018Upw3aA9syy5Jm84F1xp9f

Adds clarification that views only affect Console UI display, not how data is exported to JSON, CSV, or other formats. https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

Reorganizes the page to provide better context before diving into details: - Adds introduction explaining what dataset schema is and its two components - Moves file structure section before examples - Reorganizes into clear Fields and Views sections as parallel concepts - Consolidates reference tables at the end - Maintains all existing content but in a more logical flow The page now follows the same pattern as other actor definition pages (input_schema, output_schema) where concepts are introduced before examples. https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

jancurn · 2026-05-21T15:04:12Z

-            }
-        }
-    }
+    "fields": { /* JSON Schema describing each item */ },


Instead of these comments, keep there the short examples

Addresses review feedback to show actual field/view examples instead of comments in the schema components overview. https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

TC-MO

Thanks Jan! Left some inline suggestions, mostly:

Bold reserved for UI elements (a few bullet lists use term as a label pattern)
"Output tab UI" > "Output tab" for consistency (the tab is in the UI)
A couple of gerund headings and one all-caps "NOT" to soften
Small tightening passes where prose restates what's just above
One technical fix: $schema in the example uses draft-07 but the reference table specifies Draft 2020-12, changed it for consistency's sake

One pattern that's worth applying consistently across the page (not just the bullets at LOC15-16): views is required, fields is optional, so required-first ordering
would apply to:

The example JSON at LOC20-38 (views before fields)
The major sections (move Views section above Fields section)
The reference table at LOC427-428 (views row before fields row)

Happy to make those changes myself if that is easier.

TC-MO · 2026-05-26T11:17:33Z

+}
+```
+
+The first view defined becomes the default tab.


I would cut this, it is already stated at LOC 213.

TC-MO · 2026-05-26T11:20:27Z

+### Flatten in Actor code
+
+Alternatively, flatten nested structures in your Actor code before calling `Actor.pushData()`.


Single sentence subsections are not the greatest practice. I would recommend removing H3 and folding into previous section.

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

- Remove redundant "UI" from "Output tab UI" throughout - Change "two main components" to "two components" - Remove sentence that rephrases the bullets - Simplify field and AI agent descriptions - Rename "Example with field metadata" to "Field metadata example" - Update JSON Schema to 2020-12 draft for consistency - Reword validation link to start with verb - Remove bold from bullet points (reserved for UI elements) - Change "What views are NOT for" to "What views are not for" - Simplify Google Maps example sentence - Fold single-sentence subsection into previous section - Various prose cleanup for conciseness https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

claude added 2 commits May 21, 2026 11:12

docs: clarify views don't control export formats

12dd6e5

Adds clarification that views only affect Console UI display, not how data is exported to JSON, CSV, or other formats. https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

jancurn requested a review from TC-MO May 21, 2026 11:28

jancurn changed the title ~~docs: add guidance on why and when to use dataset views~~ [WIP] docs: add guidance on why and when to use dataset views May 21, 2026

docs: convert schema components table to bullet list

fc9c604

https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

jancurn changed the title ~~[WIP] docs: add guidance on why and when to use dataset views~~ docs: restructure dataset schema page with introduction and guidance May 21, 2026

jancurn commented May 21, 2026

View reviewed changes

docs: replace placeholder comments with short examples

07bc8a6

Addresses review feedback to show actual field/view examples instead of comments in the schema components overview. https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

jancurn changed the title ~~docs: restructure dataset schema page with introduction and guidance~~ [WIP] docs: restructure dataset schema page with introduction and guidance May 21, 2026

jancurn changed the title ~~[WIP] docs: restructure dataset schema page with introduction and guidance~~ docs: restructure dataset schema page with introduction and guidance May 21, 2026

TC-MO requested changes May 26, 2026

View reviewed changes

martin-sabo-98 mentioned this pull request May 29, 2026

docs: Add Actor task publication guide #2582

Merged

jancurn and others added 11 commits May 31, 2026 23:32

Update sources/platform/actors/development/actor_definition/dataset_s…

1120301

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

2eed285

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

f79917e

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

37a5abb

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

12c8e1f

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

f135d74

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

4e7cc2e

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/actor_definition/dataset_s…

b67d59d

…chema/index.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Merge branch 'master' into claude/slack-session-oDBaR

608769c

docs: fix emphasis style to use underscores

71b6a5e

https://claude.ai/code/session_01JyTmwWUsZaN7436BBgxwvG

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: restructure dataset schema page with introduction and guidance#2554

docs: restructure dataset schema page with introduction and guidance#2554
jancurn wants to merge 17 commits into
masterfrom
claude/slack-session-oDBaR

jancurn commented May 21, 2026 •

edited

Loading

Uh oh!

apify-service-account commented May 21, 2026 •

edited

Loading

Uh oh!

jancurn May 21, 2026

Uh oh!

TC-MO left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TC-MO May 26, 2026

Uh oh!

Uh oh!

TC-MO May 26, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		### Flatten in Actor code

		Alternatively, flatten nested structures in your Actor code before calling `Actor.pushData()`.

Conversation

jancurn commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Context

Test plan

Uh oh!

apify-service-account commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jancurn May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TC-MO May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TC-MO May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jancurn commented May 21, 2026 •

edited

Loading

apify-service-account commented May 21, 2026 •

edited

Loading