---
name: clean-json-toolkit
description: Local JSON / JSONL inspection and manipulation toolkit. Inspect deeply nested structures (path tree, types, sample values per path), query with a jq-style path language (no external jq), flatten nested objects/arrays into dot-notation maps and unflatten them back, and validate against a small pragmatic schema (required/type/min/max/regex/enum/item_type). Pure Python 3 standard library, no third-party dependencies, no remote calls.
license: MIT
metadata: {"openclaw":{"requires":{"bins":["python3"]},"primaryEnv":null,"homepage":"https://clawhub.ai/gopendrasharma89-tech/clean-json-toolkit"}}
---

# clean-json-toolkit

v0.1.0

Fourth member of the `clean-*` family. csv handles structured tabular data, text handles unstructured strings, log handles timestamped logs, and **json** handles nested data — API responses, config files, JSONL event streams.

Pure Python 3 standard library. No `jq`, no `jsonschema`, no pip installs.

## Scripts

- `scripts/inspect.py` — profile a `.json` or `.jsonl` file: tree of every distinct path with types, counts, and N sample values per path.
- `scripts/query.py` — jq-style path queries. `.key.nested`, `.key[0]`, `.[]` iterate, `.key.[].field` map. Output modes: `--json` / `--jsonl` / `--lines` / `--raw`. JSONL inputs implicitly iterate at the top level.
- `scripts/flatten.py` — flatten nested JSON into dot-notation keys. Reversible with `--unflatten`. Roundtrip-safe.
- `scripts/validate.py` — validate against a small schema (`required`, `type`, `min`/`max`, `min_length`/`max_length`, `enum`, `regex`, `item_type`, `allow_extra`).
- `scripts/check_deps.sh` — verify `python3`.

## Quick start

```bash
# Inspect
python3 scripts/inspect.py response.json
python3 scripts/inspect.py events.jsonl --max-samples 5

# Query
python3 scripts/query.py data.json '.meta'
python3 scripts/query.py data.json '.users.[].email' --raw
python3 scripts/query.py events.jsonl '.amount' --lines

# Flatten + unflatten roundtrip
python3 scripts/flatten.py config.json flat.json
python3 scripts/flatten.py flat.json nested.json --unflatten

# Validate
python3 scripts/validate.py users.jsonl --schema schema.json
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | success / one or more results |
| 1 | zero results / validation failed / empty input |
| 2 | bad arguments / unsafe path / missing file / invalid JSON / bad schema |

## Safety

- Pure Python 3 stdlib. No `eval`, no `subprocess`, no remote calls.
- All paths validated against safe-path policy (same as the other `clean-*` toolkits).
- Hand-rolled query path tokenizer.

## Pairs well with

- [`clean-csv-toolkit`](https://clawhub.ai/gopendrasharma89-tech/clean-csv-toolkit)
- [`clean-text-toolkit`](https://clawhub.ai/gopendrasharma89-tech/clean-text-toolkit)
- [`clean-log-toolkit`](https://clawhub.ai/gopendrasharma89-tech/clean-log-toolkit)

## License

MIT