Skip to content
JournalTORIS / FIELD NOTES

← Blog Project notes

Our JSON Generation Script Was Product Code Too

A look back at the Node.js job that converted educational content into ViewerData and saved it to public/data, and how input validation at the conversion boundary cut screen errors.

2 min read Read the Korean original

Joohwan Yu · Founder, Full Stack Developer

Toris · Published

Contents

At first, the script that turned educational content into ViewerData felt like a side tool. It just had to build chapter, learningScenes, and metaData and save the result to a file. But the screens ran on the assumption that this output was correct. A small mistake at the generation step could later show up as odd behavior in the viewer.

We had to decide where values come from first

I wasn’t sure where to inject values like field and the id of the left-hand content. If the generator guesses every value, callers have it easy. But when the data isn’t what you expected, it becomes hard to trace why a value ended up there. If you leave every field to the caller instead, the generator’s role gets blurry and repeated code grows.

If I drew this boundary again today, I would take the meaningful values that differ per project as input and have the generator own the structural defaults. When a required value is missing, it’s better to say which input is absent than to fill in an empty string and produce a file anyway.

Why I separate reading, converting, and writing

At the time, I used Node.js to read the files in data/kids and data/default and save the results to public/data. Separating file system access from object conversion makes it easier to look at the conversion rules on their own. You can check what scene structure a single input produces without writing any file.

For validation criteria, the first things that come to mind are duplicate scene IDs, missing required content, and whether referenced IDs actually exist. TypeScript types help while you write code, but you still need a separate check that the real data read from a file matches the types. A type declaration alone can’t turn bad external JSON into good JSON.

What I’d leave behind if I rebuilt it

Today I would make the success message include the number of files and scenes processed, not just the output path. For failed inputs, I’d report the path and the reason, but I wouldn’t dump all the data into the log. I’d also review the ID policy at generation time so that comparing result files doesn’t show unnecessary changes.

This experience changed my “it’s only a developer script, so it can be sloppy” attitude. Code that produces a product’s data is part of the product, even if no user ever clicks it. Explaining, at the input stage, errors that are hard to find on screen was one of the generator’s most important features.

Related post: The role of scene IDs

Advertisement