A film journal can look correct on screen and still produce an unusable export. Two viewings of the same film might collapse into one row. A missing rating might become zero. A note containing a comma might shift the remaining values into the wrong columns.
The design problem is not merely adding a Download CSV button. It is defining what the exported data means and checking that another tool can preserve it. The following is a proposed export contract for a personal film journal, not a description of a deployed feature.
Start with the viewing event
Use one row per viewing event. A film identifier describes the work; an event identifier describes this particular viewing. Rewatching the same film produces another event, even when the title, edition, and rating happen to match.
Keep the work identifier and edition details in separate fields. The edition can be unknown. An export should not infer it from the film title, and an importer should not merge events just because those titles match.
A small contract might include schema_version, event_id, work_id, title, release_year, viewed_on, date_precision, viewing_status, edition_note, rating_value, rating_scale, and notes. Each column needs a documented meaning. Some values will legitimately be empty.
Preserve what the user knows about time
A date-only viewing entry should remain a date. Turning it into midnight UTC invents a time and can display as the previous day when another tool applies a local timezone.
If the product allows approximate dates, export that precision explicitly. A user who remembers October but not the day should not acquire an invented October 1 entry. Define whether viewed_on accepts a year, a year-month, or a full date, and use date_precision to make the interpretation unambiguous.
If actual timestamps are also supported, define their offset handling separately. Do not silently make a date-only field serve both jobs.
Give empty values a meaning
For this contract, an empty rating_value means “not rated,” not zero. A real zero is a value only if the declared rating scale allows it. Preserve rating_scale so a three on a five-point scale is not reinterpreted as three out of ten.
CSV does not supply those semantics for you. Document them in the export format description. If the product needs to distinguish “unknown,” “not applicable,” and “intentionally left blank,” add an explicit status field instead of pretending one empty cell carries all three meanings.
Likewise, viewing_status should distinguish completed and unfinished entries. Having a row in the journal is not sufficient evidence that someone finished the film.
Quote text correctly, then test a real round trip
RFC 4180 describes a common CSV format in which fields containing commas, double quotes, or line breaks are enclosed in double quotes. A double quote inside a quoted field is represented by two double quotes. That is why splitting every physical line on commas is not a safe parser for free-form film notes.
Use a CSV writer and parser that handle those rules. Choose and document UTF-8 for this export so accented titles and notes have an explicit encoding contract; that is a design choice here, not a claim that RFC 4180 mandates UTF-8.
Round-trip test a note with a comma, a quoted phrase, and a paragraph break. Compare the restored value with the original string, rather than judging success from whether a spreadsheet opens. Include a title with accents and an unrated event in the same test set.
Preview imports before changing the journal
An import preview should show row counts, a few representative entries, and errors tied to the affected record and field. Unknown columns can be reported without silently discarding them. Missing required columns should produce an actionable message before records are written.
Use stable event identifiers to make a second import of the same file recognizable. Define a conflict policy: skip identical records, and present changed records for a deliberate update decision. Do not silently append duplicates or overwrite newer notes.
If an identifier is meaningful only within one journal, include that journal’s namespace in the identity contract. “Event 12” from two separate collections is not automatically the same event.
Keep catalog discovery outside the viewing record
A catalog link can help someone find a film, but it does not establish that they watched it. In a journal associated with DVDWholesaleShop’s catalog, browsing or saving a product should therefore remain separate from creating a viewing event.
That separation also keeps an export useful when product pages change. The journal should retain the user’s title, date, edition note, and response without requiring a live commercial URL to explain every row.
Acceptance means preserved meaning
Before calling the export ready, import it into an empty test journal and check repeated viewings, approximate dates, missing editions, unrated entries, and multiline notes. Import the same file again and verify the documented conflict behavior.
Opening the file is a format check. Recovering the same events and the same uncertainty is the more useful acceptance criterion.
Top comments (0)