Sprint 2: Import Validation & Preview #2

New issue

Closed

opened 2026-05-19 05:04:47 +00:00 by foravo_admin · 0 comments

foravo_admin commented

2026-05-19 05:04:47 +00:00

Owner

Imported from GitHub issue conorgregson/worldbuilding-codex#27.

Source: https://github.com/conorgregson/worldbuilding-codex/issues/27
Original author: @conorgregson
Original state: closed

Goal

Add the import validation and preview layer for Worldbuilding Codex v1.4 by allowing users to upload an exported world JSON file, validate it, and review what it contains before anything is saved.

This sprint establishes the safety layer for import by rejecting invalid files clearly and showing a useful preview for valid exports.

Context

Sprint 1 adds world export.

Sprint 2 builds on that export format by adding an import flow that can validate uploaded JSON files and show users what would be imported.

This sprint should not save imported data yet. It should focus on validation, error handling, preview, accessibility, and responsive layout.

Scope

Add an import entry point from the worlds area.
Add a JSON file upload control.
Read or submit the selected export file.
Add a backend validation endpoint.
Validate required top-level export fields.
Validate export metadata.
Validate world data.
Validate entities, relationships, events, participants, and tags where available.
Validate that relationships reference exported entities.
Validate that event participants reference exported events and entities.
Return clear validation errors for invalid imports.
Return preview data for valid imports.
Show world title and record counts before import.
Make it clear that preview does not save data.
Confirm failed validation does not create partial data.
Polish validation, error, and preview states.

Suggested Route Behavior

POST /api/worlds/import/validate

The route should:

Require authentication.
Parse the uploaded JSON safely.
Reject malformed JSON.
Reject unsupported export versions.
Validate the export structure.
Validate internal references.
Return preview data for valid exports.
Avoid saving any imported data.

Acceptance Criteria

Users can open an import flow.
Users can choose a .json file.
Malformed JSON files show a clear error.
Unsupported export versions show a clear error.
Missing required export sections show clear validation errors.
Invalid world data shows clear validation errors.
Invalid entity data shows clear validation errors.
Invalid relationship references show clear validation errors.
Invalid event participant references show clear validation errors.
Valid export files show an import preview.
Preview includes world title.
Preview includes entity count.
Preview includes relationship count.
Preview includes event count.
Preview includes participant count where available.
Preview includes tag count where available.
The UI clearly explains that preview does not save imported data.
Validation does not create a new world.
Validation failure does not partially save data.
Import validation controls are labelled and keyboard reachable.
Import validation UI is usable on desktop and narrower screens.
No obvious console errors appear during normal validation usage.

Verification Checklist

Local Verification

Run frontend build.
Run backend build.
Log in locally.
Open the import flow.
Upload a valid exported world JSON file.
Confirm the preview appears.
Confirm the preview shows the world title.
Confirm the preview shows entity count.
Confirm the preview shows relationship count.
Confirm the preview shows event count.
Confirm the preview shows participant count where available.
Confirm the preview shows tag count where available.
Confirm no new world is created during preview.
Upload malformed JSON.
Confirm a clear invalid JSON error appears.
Upload JSON missing required top-level fields.
Confirm clear validation errors appear.
Upload JSON with a broken relationship reference.
Confirm validation catches the broken reference.
Upload JSON with a broken participant reference.
Confirm validation catches the broken reference.
Upload an unsupported export version.
Confirm validation catches the unsupported version.
Confirm the file input is labelled.
Confirm the import flow is keyboard reachable.
Confirm validation errors are readable.
Confirm the import preview is usable on desktop.
Confirm the import preview is usable on a narrow viewport.
Confirm no obvious console errors appear.

Production Verification

Hosted frontend loads successfully.
Login/authenticated flow works.
Import flow loads in production.
Valid export file preview works in production.
Invalid JSON error appears in production.
Invalid export structure errors appear in production.
No new world is created during production preview.
Import validation UI works on a narrow production viewport.
No obvious production console errors appear.

Out of Scope

Confirmed import/save behavior.
Creating imported worlds.
ID remapping.
Database transaction handling for import saves.
Duplicate world detection.
Merge import behavior.
Selective import behavior.
Editing imported data during preview.
Export changes beyond what is needed to support validation.
Public sharing work.
Printable world bible export.

Risks / Notes

Import validation should run on the server even if the frontend does basic file checks.
Validation should be strict enough to prevent broken imports but not so brittle that older compatible exports fail unnecessarily.
Validation should reject broken internal references before confirmed import work begins.
The UI should make it obvious that preview is not the same as saving.
Validation errors should be specific enough that users understand why the file failed.
Sprint 2 intentionally avoids saving imported data so import safety can be tested separately.
Confirmed save behavior and ID remapping are intentionally left for Sprint 3.

Imported from GitHub issue `conorgregson/worldbuilding-codex#27`. Source: https://github.com/conorgregson/worldbuilding-codex/issues/27 Original author: @conorgregson Original state: closed  --- ## Goal Add the import validation and preview layer for Worldbuilding Codex v1.4 by allowing users to upload an exported world JSON file, validate it, and review what it contains before anything is saved. This sprint establishes the safety layer for import by rejecting invalid files clearly and showing a useful preview for valid exports. --- ## Context Sprint 1 adds world export. Sprint 2 builds on that export format by adding an import flow that can validate uploaded JSON files and show users what would be imported. This sprint should not save imported data yet. It should focus on validation, error handling, preview, accessibility, and responsive layout. --- ## Scope - Add an import entry point from the worlds area. - Add a JSON file upload control. - Read or submit the selected export file. - Add a backend validation endpoint. - Validate required top-level export fields. - Validate export metadata. - Validate world data. - Validate entities, relationships, events, participants, and tags where available. - Validate that relationships reference exported entities. - Validate that event participants reference exported events and entities. - Return clear validation errors for invalid imports. - Return preview data for valid imports. - Show world title and record counts before import. - Make it clear that preview does not save data. - Confirm failed validation does not create partial data. - Polish validation, error, and preview states. --- ## Suggested Route Behavior ```txt POST /api/worlds/import/validate ``` The route should: - Require authentication. - Parse the uploaded JSON safely. - Reject malformed JSON. - Reject unsupported export versions. - Validate the export structure. - Validate internal references. - Return preview data for valid exports. - Avoid saving any imported data. --- ## Acceptance Criteria - [x] Users can open an import flow. - [x] Users can choose a .json file. - [x] Malformed JSON files show a clear error. - [x] Unsupported export versions show a clear error. - [x] Missing required export sections show clear validation errors. - [x] Invalid world data shows clear validation errors. - [x] Invalid entity data shows clear validation errors. - [x] Invalid relationship references show clear validation errors. - [x] Invalid event participant references show clear validation errors. - [x] Valid export files show an import preview. - [x] Preview includes world title. - [x] Preview includes entity count. - [x] Preview includes relationship count. - [x] Preview includes event count. - [x] Preview includes participant count where available. - [x] Preview includes tag count where available. - [x] The UI clearly explains that preview does not save imported data. - [x] Validation does not create a new world. - [x] Validation failure does not partially save data. - [x] Import validation controls are labelled and keyboard reachable. - [x] Import validation UI is usable on desktop and narrower screens. - [x] No obvious console errors appear during normal validation usage. --- ## Verification Checklist ### Local Verification - [x] Run frontend build. - [x] Run backend build. - [x] Log in locally. - [x] Open the import flow. - [x] Upload a valid exported world JSON file. - [x] Confirm the preview appears. - [x] Confirm the preview shows the world title. - [x] Confirm the preview shows entity count. - [x] Confirm the preview shows relationship count. - [x] Confirm the preview shows event count. - [x] Confirm the preview shows participant count where available. - [x] Confirm the preview shows tag count where available. - [x] Confirm no new world is created during preview. - [x] Upload malformed JSON. - [x] Confirm a clear invalid JSON error appears. - [x] Upload JSON missing required top-level fields. - [x] Confirm clear validation errors appear. - [x] Upload JSON with a broken relationship reference. - [x] Confirm validation catches the broken reference. - [x] Upload JSON with a broken participant reference. - [x] Confirm validation catches the broken reference. - [x] Upload an unsupported export version. - [x] Confirm validation catches the unsupported version. - [x] Confirm the file input is labelled. - [x] Confirm the import flow is keyboard reachable. - [x] Confirm validation errors are readable. - [x] Confirm the import preview is usable on desktop. - [x] Confirm the import preview is usable on a narrow viewport. - [x] Confirm no obvious console errors appear. ### Production Verification - [x] Hosted frontend loads successfully. - [x] Login/authenticated flow works. - [x] Import flow loads in production. - [x] Valid export file preview works in production. - [x] Invalid JSON error appears in production. - [x] Invalid export structure errors appear in production. - [x] No new world is created during production preview. - [x] Import validation UI works on a narrow production viewport. - [x] No obvious production console errors appear. --- ## Out of Scope - Confirmed import/save behavior. - Creating imported worlds. - ID remapping. - Database transaction handling for import saves. - Duplicate world detection. - Merge import behavior. - Selective import behavior. - Editing imported data during preview. - Export changes beyond what is needed to support validation. - Public sharing work. - Printable world bible export. --- ### Risks / Notes - Import validation should run on the server even if the frontend does basic file checks. - Validation should be strict enough to prevent broken imports but not so brittle that older compatible exports fail unnecessarily. - Validation should reject broken internal references before confirmed import work begins. - The UI should make it obvious that preview is not the same as saving. - Validation errors should be specific enough that users understand why the file failed. - Sprint 2 intentionally avoids saving imported data so import safety can be tested separately. - Confirmed save behavior and ID remapping are intentionally left for Sprint 3.

foravo_admin

2026-05-19 05:04:47 +00:00