A converter should preserve meaning, not just produce valid JSON. When source data contains direction, display order, picture clues, abbreviations, and fragments, dropping any of those details can make the export look correct while still being incomplete.
Why it happens
I was converting crossword-style records into a simpler question-and-answer format. The first result included many normal words, but it silently excluded short answers, abbreviations, fragments, and some clues from one direction.
The JSON passed basic validation. The data was still wrong because the filtering rules had removed valid source content.
Preserve source meaning explicitly
- Keep direction metadata. Store whether each clue is Across or Down while parsing.
- Include every real clue. Do not assume one-letter answers or abbreviations are invalid.
- Sort intentionally. Output all Across clues first, then all Down clues, while preserving their original order inside each group.
-
Normalize only presentation. Changing answer casing is safe when required, but it should not change which records exist.
-
Represent picture clues clearly. Use a readable label or marker when the source has an image instead of clue text.
Why plausible filters can fail
A rule such as “answers must have at least two letters” may sound helpful, but crosswords often use single letters, abbreviations, and partial words. The cause is an assumption borrowed from ordinary word lists. The fix is to trust the puzzle’s own clue structure and filter only records that are genuinely missing or malformed.
Test structure, not only syntax
A useful test should check more than whether the output parses. It should verify the expected total number of clues, confirm representative short and picture-based answers, and assert the complete order of Across and Down entries.
A small fixture with known answers is especially valuable. It catches omissions and ordering changes immediately, even when the JSON remains perfectly valid.
Common mistake
Problem: The export contains the main words but misses unusual entries.
Cause: A generic “valid word” filter decides what belongs in the puzzle.
Fix: Preserve all entries connected to a real clue, then validate completeness against a known puzzle.
Make omissions visible
Compare source and output counts per direction, then report each rejected record with a reason. Keep a stable source identifier in an intermediate representation so duplicated answer text does not collapse distinct clues. Include fixtures for an empty clue label, a picture clue, repeated answers, and one-letter entries.
When converting structured data, define correctness as semantic fidelity: all meaningful records, in the intended order, with presentation changes kept separate. The next action is to add one completeness-and-order test before trusting any generated export.