Deterministic CSV ↔ JSON Conversion Preflight

Use this skill before promising a CSV-to-JSON or JSON-to-CSV conversion. It turns an underspecified “simple converter” request into a bounded, testable data contract and supplies dependency-free Python reference implementations.

First decide the contract

Ask or explicitly default these points:

1. JSON shape: one array of objects, or NDJSON (one object per line).
2. CSV dialect: delimiter, quote character, header presence, and encoding. Safe default: UTF-8 with comma delimiter and RFC-style quoting.
3. Types: CSV has no native types. Safe default: preserve every field as a string; do not silently coerce IDs, dates, booleans, or leading-zero values.
4. Missing versus empty: a missing JSON key and an empty string are distinct in JSON but collapse to the same empty CSV cell unless a sentinel is agreed.
5. Nested values: reject nested objects/arrays by default. Flattening needs an explicit path convention and escaping rule.
6. Column order: use the first-seen union of keys for deterministic output, or require an explicit schema.

CSV to JSON: Python 3.10+ standard library

#!/usr/bin/env python3
import argparse, csv, json, sys
from pathlib import Path

def convert(src: Path, dst: Path, delimiter: str = ",") -> None:
    with src.open("r", encoding="utf-8-sig", newline="") as handle:
        reader = csv.DictReader(handle, delimiter=delimiter)
        if reader.fieldnames is None:
            raise ValueError("CSV must contain a header row")
        if len(set(reader.fieldnames)) != len(reader.fieldnames):
            raise ValueError("CSV contains duplicate header names")
        rows = list(reader)
    with dst.open("w", encoding="utf-8", newline="
") as handle:
        json.dump(rows, handle, ensure_ascii=False, indent=2)
        handle.write("
")

def main() -> int:
    p = argparse.ArgumentParser()
    p.add_argument("input", type=Path)
    p.add_argument("output", type=Path)
    p.add_argument("--delimiter", default=",")
    args = p.parse_args()
    if len(args.delimiter) != 1:
        p.error("--delimiter must be exactly one character")
    try:
        convert(args.input, args.output, args.delimiter)
    except (OSError, csv.Error, ValueError) as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

JSON to CSV: deterministic union of flat keys

#!/usr/bin/env python3
import argparse, csv, json, sys
from pathlib import Path

def convert(src: Path, dst: Path) -> None:
    with src.open("r", encoding="utf-8") as handle:
        rows = json.load(handle)
    if not isinstance(rows, list) or any(not isinstance(x, dict) for x in rows):
        raise ValueError("input must be a JSON array of objects")
    fields, seen = [], set()
    for row in rows:
        for key, value in row.items():
            if not isinstance(key, str):
                raise ValueError("all object keys must be strings")
            if isinstance(value, (dict, list)):
                raise ValueError(f"nested value at key {key!r}")
            if key not in seen:
                seen.add(key); fields.append(key)
    with dst.open("w", encoding="utf-8", newline="") as handle:
        writer = csv.DictWriter(handle, fieldnames=fields, extrasaction="raise")
        writer.writeheader()
        for row in rows:
            writer.writerow({k: "" if row.get(k) is None else row.get(k, "") for k in fields})

def main() -> int:
    p = argparse.ArgumentParser(); p.add_argument("input", type=Path); p.add_argument("output", type=Path)
    args = p.parse_args()
    try: convert(args.input, args.output)
    except (OSError, json.JSONDecodeError, ValueError, csv.Error) as exc:
        print(f"error: {exc}", file=sys.stderr); return 2
    return 0

if __name__ == "__main__": raise SystemExit(main())

Minimum verification matrix

• UTF-8 and non-ASCII text.
• Commas, quotes, and embedded newlines inside quoted fields.
• Missing keys and empty strings.
• Leading-zero identifiers such as 00123.
• Empty input and header-only CSV.
• Duplicate CSV headers.
• Invalid JSON top-level shape.
• Nested arrays/objects rejected with the exact offending key.
• Deterministic byte-for-byte output across two runs.

Delivery checklist

Report the chosen contract, exact commands, fixture hashes, test results, and any lossy mapping. Never claim round-trip equivalence when missing/null/empty distinctions or scalar types were collapsed.