spb/ultra-sharp-agent-skills Public

1---2name: processing-json3description: Creates, reads, modifies, validates, and queries JSON and JSON Lines files. Use when the user asks to read, write, parse, edit, update, merge, validate, pretty-print, or query a .json or .jsonl file, mentions JSON data or JSON Lines, or asks to fix invalid JSON. Do not use for YAML/TOML config files or for designing APIs.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Processing JSON1213## When to use / when NOT to use14- **Use for:** any task where a `.json` or `.jsonl` file is the input or output — creating, parsing, editing, validating, querying.15- **Do NOT use for:** YAML/TOML config files or API design discussions.1617## Quick reference — one default per operation1819**Read / write — Python stdlib `json`:**20```python21import json22with open("data.json", encoding="utf-8") as f:23    data = json.load(f)                       # load() IS the syntax validator2425with open("data.json", "w", encoding="utf-8") as f:26    json.dump(data, f, indent=2, ensure_ascii=False)27```2829**JSON Lines — one object per line, never json.load the whole file:**30```python31records = [json.loads(line) for line in open("data.jsonl", encoding="utf-8") if line.strip()]32with open("out.jsonl", "w", encoding="utf-8") as f:33    for r in records:34        f.write(json.dumps(r, ensure_ascii=False) + "\n")35```3637**Modify — always atomically** (temp file + rename; a crash mid-write can't corrupt the original):38```python39import json, os, tempfile40with open("data.json", encoding="utf-8") as f:41    data = json.load(f)42data["version"] = 243fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath("data.json")))44with os.fdopen(fd, "w", encoding="utf-8") as f:45    json.dump(data, f, indent=2, ensure_ascii=False)46os.replace(tmp, "data.json")47```4849**Query — escape hatch for large files:** `jq '.items[] | select(.active)' big.json` (requires jq installed: `brew install jq`). For everything else, load and filter in Python.5051**Schema validation:** `pip install jsonschema`, then `jsonschema.validate(instance=data, schema=schema)`.5253## Rules54- **Never edit JSON with regex or string replacement.** Parse → mutate → dump. Always.55- Preserve key order: Python dicts keep insertion order; do not pass `sort_keys=True` unless asked.56- `indent=2, ensure_ascii=False` for human-facing files; single-line compact only for machine-to-machine output.5758## Workflow591. Load the input (`json.load` / line-by-line for `.jsonl`). A parse error here is a finding, not a failure — see edge cases.602. Apply the change/query in Python on the parsed structure.613. Write atomically (recipe above).624. **Validate:** re-open and `json.load` the written file; for `.jsonl`, re-parse every line. Only then report success.635. Report the output path and what changed (keys touched, records added/removed).6465## Edge cases & failure modes66- **Malformed JSON** → `json.JSONDecodeError` includes line and column; report it verbatim (e.g. "Expecting ',' delimiter: line 12 column 3") and show the offending line. Common causes: trailing commas, single quotes, comments — fix precisely, don't guess.67- **`NaN`/`Infinity` in input** → stdlib accepts them but they are NOT valid JSON; re-emit with `json.dump(..., allow_nan=False)` after replacing them with `null` (confirm with the user).68- **Missing dependency** → only third-party need: `pip install jsonschema` (schema validation) or `brew install jq`.69- **Huge file (>500 MB)** → if it's `.jsonl`, stream line-by-line; if a single JSON document, use `jq` rather than loading into Python.70- **Empty file** → report "file is empty — not valid JSON (an empty JSON file should contain `{}` or `[]`)" and ask which the user wants.71- **Duplicate keys** → `json.load` silently keeps the last one; when auditing, parse with `object_pairs_hook=list` to detect them.7273## References74Deeper recipes (merging, diffing, flattening, jsonl↔json, encoding traps): see [references/recipes.md](references/recipes.md).75