{
  "slug": "flatten-json",
  "name": "gizza-ai/flatten-json",
  "version": "0.1.0",
  "title": "Flatten JSON — Nested JSON to Dot / Bracket Key Paths (and Back) — gizza.ai",
  "description": "Flatten nested JSON into single-level dot or bracket key paths, or unflatten those paths back into nested JSON. Custom separator, CSV/pairs output, no upload.",
  "tags": [
    "flatten json",
    "unflatten json",
    "json to dot notation",
    "nested json to flat",
    "json key paths",
    "json to csv keys",
    "dot notation json",
    "json flattener",
    "bracket notation",
    "json to env keys"
  ],
  "category": "data",
  "urls": {
    "page": "https://gizza.ai/tools/flatten-json/",
    "markdown": "https://gizza.ai/tools/flatten-json/index.md",
    "descriptor": "https://gizza.ai/tools/flatten-json/tool.json",
    "deep_link_example": "https://gizza.ai/tools/flatten-json/?json=%7B%22user%22%3A%7B%22name%22%3A%22Ada%22%2C%22tags%22%3A%5B%22admin%22%2C%22beta%22%5D%7D%2C%22active%22%3Atrue%7D&direction=flatten&separator=.&array_notation=bracket&max_depth=0&flatten_arrays=true&preserve_empty=true&key_case=preserve&output=json&pretty=true&indent=2"
  },
  "cli": "gizza tool flatten-json '{\"user\":{\"name\":\"Ada\",\"tags\":[\"admin\",\"beta\"]},\"active\":true}'",
  "tool": {
    "description": "Flatten a nested JSON document into a single-level map of path -> value, and rebuild the nested document from those paths. direction='flatten' (default) turns {\"user\":{\"name\":\"Ada\",\"tags\":[\"a\",\"b\"]}} into {\"user.name\":\"Ada\",\"user.tags[0]\":\"a\",\"user.tags[1]\":\"b\"}; direction='unflatten' reverses it; 'auto' picks the direction from the input shape. separator sets the key joiner ('.' default, '_' or '/' also common) and array_notation chooses tags[0] (bracket, default) or tags.0 (separator) for array elements — both round-trip. max_depth flattens only the first N levels, flatten_arrays=false keeps arrays whole, preserve_empty=true keeps {} / [] keys, and key_case makes ENV-style (upper) or SQL-style (lower) keys. output returns the flat result as JSON, path=value pairs, a two-column key,value CSV for spreadsheets, or just the path list. Runs locally — the document never leaves the device.",
    "parameters": {
      "additionalProperties": false,
      "properties": {
        "array_notation": {
          "default": "bracket",
          "description": "How array elements appear in a path. 'bracket' (default) writes tags[0]; 'separator' writes tags.0 using the separator. This also decides how a path is read back: with 'separator' an all-digit segment rebuilds an array, with 'bracket' it stays an object key literally named \"0\".",
          "enum": [
            "bracket",
            "separator"
          ],
          "type": "string"
        },
        "direction": {
          "default": "flatten",
          "description": "Which way to convert. 'flatten' (default) turns nested JSON into path -> value pairs; 'unflatten' rebuilds nested JSON from those pairs; 'auto' unflattens only when the input is a one-level object whose keys already look like paths, and flattens otherwise.",
          "enum": [
            "flatten",
            "unflatten",
            "auto"
          ],
          "type": "string"
        },
        "flatten_arrays": {
          "default": true,
          "description": "Expand arrays into indexed paths (default true). Set false to keep every array whole as a JSON value while still flattening objects — useful when a list is one logical cell. Flatten only.",
          "type": "boolean"
        },
        "indent": {
          "default": 2,
          "description": "Spaces per indent level when pretty=true. Default 2; 0 is the same as pretty=false.",
          "maximum": 8,
          "minimum": 0,
          "type": "integer"
        },
        "json": {
          "description": "The JSON document to convert. Flattening accepts an object or an array, e.g. {\"user\":{\"name\":\"Ada\",\"tags\":[\"a\"]}}; unflattening accepts a flat object of path -> value, e.g. {\"user.name\":\"Ada\"}. Capped at 5 MB, 100 levels of nesting and 200000 keys.",
          "type": "string"
        },
        "key_case": {
          "default": "preserve",
          "description": "Case of the generated paths: 'preserve' (default) keeps the source keys, 'upper' gives ENV-style keys (with separator='_': DB_HOST), 'lower' gives SQL-style column keys. Upper/lower are lossy — the original key case cannot be recovered by unflattening. Flatten only.",
          "enum": [
            "preserve",
            "upper",
            "lower"
          ],
          "type": "string"
        },
        "max_depth": {
          "default": 0,
          "description": "How many levels to flatten. 0 (default) is unlimited. With 2, {\"a\":{\"b\":{\"c\":1}}} becomes {\"a.b\":{\"c\":1}} — anything deeper is left as a nested JSON value. Flatten only.",
          "maximum": 100,
          "minimum": 0,
          "type": "integer"
        },
        "output": {
          "default": "json",
          "description": "Shape of the flattened result: 'json' (default) a JSON object of path -> value; 'pairs' one path=value line each (strings unquoted, so db.host=localhost); 'csv' a two-column key,value CSV with a header row for spreadsheets; 'paths' just the paths, one per line. Flatten only — unflattening always returns nested JSON, so leave this at json.",
          "enum": [
            "json",
            "pairs",
            "csv",
            "paths"
          ],
          "type": "string"
        },
        "preserve_empty": {
          "default": true,
          "description": "Keep empty objects and arrays as {} / [] leaf entries (default true), so the key survives and the document round-trips. Set false to drop those keys entirely. Flatten only.",
          "type": "boolean"
        },
        "pretty": {
          "default": true,
          "description": "Indent the JSON output (default true). Set false for one compact line. Ignored by the pairs/csv/keys outputs.",
          "type": "boolean"
        },
        "separator": {
          "default": ".",
          "description": "String that joins object keys in a path. Default '.' (user.name); '_' gives user_name and '/' gives user/name. Any 1-8 characters except '[' and ']'. If a key in your document already contains the separator the run fails rather than silently merging two paths — pick another separator.",
          "type": "string"
        }
      },
      "required": [
        "json"
      ],
      "type": "object"
    }
  }
}