[{"data":1,"prerenderedAt":768},["ShallowReactive",2],{"guide-csv-to-nested-json":3},{"id":4,"title":5,"body":6,"date":759,"description":760,"extension":761,"meta":762,"navigation":763,"path":764,"readingTime":119,"seo":765,"stem":766,"__hash__":767},"guides\u002Fguides\u002Fcsv-to-nested-json.md","Converting Flat CSV to Nested JSON",{"type":7,"value":8,"toc":744},"minimark",[9,14,18,21,25,28,58,61,185,196,200,203,278,281,285,288,313,316,489,503,507,512,515,530,533,537,540,548,551,555,561,610,614,617,662,665,669,703,707,727,731,740],[10,11,13],"h2",{"id":12},"why-nested-json-matters","Why Nested JSON Matters",[15,16,17],"p",{},"CSV files are flat — every row stands alone with no inherent parent-child relationships. But most APIs and NoSQL databases expect hierarchical data where objects contain nested objects or arrays. A user record with address, orders, and preferences is a single nested document in MongoDB, but three separate CSV tables in a spreadsheet.",[15,19,20],{},"Converting flat CSV to nested JSON bridges this gap, letting you move data from spreadsheets and legacy exports into modern APIs and databases without manual restructuring.",[10,22,24],{"id":23},"the-structural-gap","The Structural Gap",[15,26,27],{},"Consider a flat CSV representing user data with embedded addresses:",[29,30,35],"pre",{"className":31,"code":32,"language":33,"meta":34,"style":34},"language-csv shiki shiki-themes github-light github-dark","id,name,street,city,zip,country\n1,Alice,123 Main St,Springfield,62704,US\n2,Bob,456 Oak Ave,Portland,97201,US\n","csv","",[36,37,38,46,52],"code",{"__ignoreMap":34},[39,40,43],"span",{"class":41,"line":42},"line",1,[39,44,45],{},"id,name,street,city,zip,country\n",[39,47,49],{"class":41,"line":48},2,[39,50,51],{},"1,Alice,123 Main St,Springfield,62704,US\n",[39,53,55],{"class":41,"line":54},3,[39,56,57],{},"2,Bob,456 Oak Ave,Portland,97201,US\n",[15,59,60],{},"The target JSON nests the address inside each user:",[29,62,66],{"className":63,"code":64,"language":65,"meta":34,"style":34},"language-json shiki shiki-themes github-light github-dark","[\n  {\n    \"id\": 1,\n    \"name\": \"Alice\",\n    \"address\": {\n      \"street\": \"123 Main St\",\n      \"city\": \"Springfield\",\n      \"zip\": \"62704\",\n      \"country\": \"US\"\n    }\n  }\n]\n","json",[36,67,68,74,79,94,108,117,130,143,156,167,173,179],{"__ignoreMap":34},[39,69,70],{"class":41,"line":42},[39,71,73],{"class":72},"sVt8B","[\n",[39,75,76],{"class":41,"line":48},[39,77,78],{"class":72},"  {\n",[39,80,81,85,88,91],{"class":41,"line":54},[39,82,84],{"class":83},"sj4cs","    \"id\"",[39,86,87],{"class":72},": ",[39,89,90],{"class":83},"1",[39,92,93],{"class":72},",\n",[39,95,97,100,102,106],{"class":41,"line":96},4,[39,98,99],{"class":83},"    \"name\"",[39,101,87],{"class":72},[39,103,105],{"class":104},"sZZnC","\"Alice\"",[39,107,93],{"class":72},[39,109,111,114],{"class":41,"line":110},5,[39,112,113],{"class":83},"    \"address\"",[39,115,116],{"class":72},": {\n",[39,118,120,123,125,128],{"class":41,"line":119},6,[39,121,122],{"class":83},"      \"street\"",[39,124,87],{"class":72},[39,126,127],{"class":104},"\"123 Main St\"",[39,129,93],{"class":72},[39,131,133,136,138,141],{"class":41,"line":132},7,[39,134,135],{"class":83},"      \"city\"",[39,137,87],{"class":72},[39,139,140],{"class":104},"\"Springfield\"",[39,142,93],{"class":72},[39,144,146,149,151,154],{"class":41,"line":145},8,[39,147,148],{"class":83},"      \"zip\"",[39,150,87],{"class":72},[39,152,153],{"class":104},"\"62704\"",[39,155,93],{"class":72},[39,157,159,162,164],{"class":41,"line":158},9,[39,160,161],{"class":83},"      \"country\"",[39,163,87],{"class":72},[39,165,166],{"class":104},"\"US\"\n",[39,168,170],{"class":41,"line":169},10,[39,171,172],{"class":72},"    }\n",[39,174,176],{"class":41,"line":175},11,[39,177,178],{"class":72},"  }\n",[39,180,182],{"class":41,"line":181},12,[39,183,184],{"class":72},"]\n",[15,186,187,188,191,192,195],{},"This nesting eliminates redundant prefixes (",[36,189,190],{},"address.street",", ",[36,193,194],{},"address.city",") and groups related fields under a common parent.",[10,197,199],{"id":198},"column-naming-conventions","Column Naming Conventions",[15,201,202],{},"The most practical approach uses dot notation in column headers to define nesting depth:",[204,205,206,219],"table",{},[207,208,209],"thead",{},[210,211,212,216],"tr",{},[213,214,215],"th",{},"CSV Column",[213,217,218],{},"JSON Path",[220,221,222,234,244,254,266],"tbody",{},[210,223,224,230],{},[225,226,227],"td",{},[36,228,229],{},"name",[225,231,232],{},[36,233,229],{},[210,235,236,240],{},[225,237,238],{},[36,239,190],{},[225,241,242],{},[36,243,190],{},[210,245,246,250],{},[225,247,248],{},[36,249,194],{},[225,251,252],{},[36,253,194],{},[210,255,256,261],{},[225,257,258],{},[36,259,260],{},"orders.0.id",[225,262,263],{},[36,264,265],{},"orders[0].id",[210,267,268,273],{},[225,269,270],{},[36,271,272],{},"orders.0.total",[225,274,275],{},[36,276,277],{},"orders[0].total",[15,279,280],{},"A conversion tool parses the dot-separated keys and builds nested objects accordingly. Numeric segments indicate array indices.",[10,282,284],{"id":283},"handling-one-to-many-relationships","Handling One-to-Many Relationships",[15,286,287],{},"Flat CSV represents one-to-many relationships through repeated parent rows:",[29,289,291],{"className":31,"code":290,"language":33,"meta":34,"style":34},"user_id,user_name,order_id,order_total\n1,Alice,101,59.99\n1,Alice,102,24.50\n2,Bob,103,112.00\n",[36,292,293,298,303,308],{"__ignoreMap":34},[39,294,295],{"class":41,"line":42},[39,296,297],{},"user_id,user_name,order_id,order_total\n",[39,299,300],{"class":41,"line":48},[39,301,302],{},"1,Alice,101,59.99\n",[39,304,305],{"class":41,"line":54},[39,306,307],{},"1,Alice,102,24.50\n",[39,309,310],{"class":41,"line":96},[39,311,312],{},"2,Bob,103,112.00\n",[15,314,315],{},"The desired output groups orders under each user:",[29,317,319],{"className":63,"code":318,"language":65,"meta":34,"style":34},"[\n  {\n    \"user_id\": 1,\n    \"user_name\": \"Alice\",\n    \"orders\": [\n      { \"order_id\": 101, \"order_total\": 59.99 },\n      { \"order_id\": 102, \"order_total\": 24.50 }\n    ]\n  },\n  {\n    \"user_id\": 2,\n    \"user_name\": \"Bob\",\n    \"orders\": [\n      { \"order_id\": 103, \"order_total\": 112.00 }\n    ]\n  }\n]\n",[36,320,321,325,329,340,351,359,385,408,413,418,422,433,444,451,474,479,484],{"__ignoreMap":34},[39,322,323],{"class":41,"line":42},[39,324,73],{"class":72},[39,326,327],{"class":41,"line":48},[39,328,78],{"class":72},[39,330,331,334,336,338],{"class":41,"line":54},[39,332,333],{"class":83},"    \"user_id\"",[39,335,87],{"class":72},[39,337,90],{"class":83},[39,339,93],{"class":72},[39,341,342,345,347,349],{"class":41,"line":96},[39,343,344],{"class":83},"    \"user_name\"",[39,346,87],{"class":72},[39,348,105],{"class":104},[39,350,93],{"class":72},[39,352,353,356],{"class":41,"line":110},[39,354,355],{"class":83},"    \"orders\"",[39,357,358],{"class":72},": [\n",[39,360,361,364,367,369,372,374,377,379,382],{"class":41,"line":119},[39,362,363],{"class":72},"      { ",[39,365,366],{"class":83},"\"order_id\"",[39,368,87],{"class":72},[39,370,371],{"class":83},"101",[39,373,191],{"class":72},[39,375,376],{"class":83},"\"order_total\"",[39,378,87],{"class":72},[39,380,381],{"class":83},"59.99",[39,383,384],{"class":72}," },\n",[39,386,387,389,391,393,396,398,400,402,405],{"class":41,"line":132},[39,388,363],{"class":72},[39,390,366],{"class":83},[39,392,87],{"class":72},[39,394,395],{"class":83},"102",[39,397,191],{"class":72},[39,399,376],{"class":83},[39,401,87],{"class":72},[39,403,404],{"class":83},"24.50",[39,406,407],{"class":72}," }\n",[39,409,410],{"class":41,"line":145},[39,411,412],{"class":72},"    ]\n",[39,414,415],{"class":41,"line":158},[39,416,417],{"class":72},"  },\n",[39,419,420],{"class":41,"line":169},[39,421,78],{"class":72},[39,423,424,426,428,431],{"class":41,"line":175},[39,425,333],{"class":83},[39,427,87],{"class":72},[39,429,430],{"class":83},"2",[39,432,93],{"class":72},[39,434,435,437,439,442],{"class":41,"line":181},[39,436,344],{"class":83},[39,438,87],{"class":72},[39,440,441],{"class":104},"\"Bob\"",[39,443,93],{"class":72},[39,445,447,449],{"class":41,"line":446},13,[39,448,355],{"class":83},[39,450,358],{"class":72},[39,452,454,456,458,460,463,465,467,469,472],{"class":41,"line":453},14,[39,455,363],{"class":72},[39,457,366],{"class":83},[39,459,87],{"class":72},[39,461,462],{"class":83},"103",[39,464,191],{"class":72},[39,466,376],{"class":83},[39,468,87],{"class":72},[39,470,471],{"class":83},"112.00",[39,473,407],{"class":72},[39,475,477],{"class":41,"line":476},15,[39,478,412],{"class":72},[39,480,482],{"class":41,"line":481},16,[39,483,178],{"class":72},[39,485,487],{"class":41,"line":486},17,[39,488,184],{"class":72},[15,490,491,492,495,496,191,499,502],{},"This requires grouping rows by a parent key (",[36,493,494],{},"user_id",") and collecting child fields (",[36,497,498],{},"order_id",[36,500,501],{},"order_total",") into an array under each group.",[10,504,506],{"id":505},"conversion-strategies","Conversion Strategies",[508,509,511],"h3",{"id":510},"dot-notation-headers","Dot-Notation Headers",[15,513,514],{},"The simplest method — rename CSV columns using dots and let a converter build the hierarchy:",[29,516,518],{"className":31,"code":517,"language":33,"meta":34,"style":34},"id,name,address.street,address.city,address.zip\n1,Alice,123 Main St,Springfield,62704\n",[36,519,520,525],{"__ignoreMap":34},[39,521,522],{"class":41,"line":42},[39,523,524],{},"id,name,address.street,address.city,address.zip\n",[39,526,527],{"class":41,"line":48},[39,528,529],{},"1,Alice,123 Main St,Springfield,62704\n",[15,531,532],{},"Works well for shallow nesting (1–2 levels). Deep nesting with arrays becomes unreadable.",[508,534,536],{"id":535},"multi-table-join","Multi-Table Join",[15,538,539],{},"Maintain separate CSV files for each entity and join them during conversion:",[29,541,546],{"className":542,"code":544,"language":545},[543],"language-text","users.csv     → id, name, email\norders.csv    → id, user_id, total\nitems.csv     → id, order_id, product, qty\n","text",[36,547,544],{"__ignoreMap":34},[15,549,550],{},"The converter reads each file, matches foreign keys, and assembles the hierarchy. This is cleaner for complex relationships but requires more setup.",[508,552,554],{"id":553},"pivot-columns","Pivot Columns",[15,556,557,558,560],{},"Use a pivot column to signal when a new child record begins. A change in the pivot value (",[36,559,494],{},") tells the converter to start a new parent object.",[204,562,563,576],{},[207,564,565],{},[210,566,567,570,573],{},[213,568,569],{},"Strategy",[213,571,572],{},"Best For",[213,574,575],{},"Complexity",[220,577,578,589,600],{},[210,579,580,583,586],{},[225,581,582],{},"Dot notation",[225,584,585],{},"Shallow nesting, 1–2 levels",[225,587,588],{},"Low",[210,590,591,594,597],{},[225,592,593],{},"Multi-table join",[225,595,596],{},"Complex relationships, multiple entities",[225,598,599],{},"Medium",[210,601,602,605,608],{},[225,603,604],{},"Pivot columns",[225,606,607],{},"One-to-many with repeated parents",[225,609,588],{},[10,611,613],{"id":612},"data-type-considerations","Data Type Considerations",[15,615,616],{},"CSV treats everything as strings. During conversion, apply type casting:",[618,619,620,633,644,653],"ul",{},[621,622,623,87,627,630,631],"li",{},[624,625,626],"strong",{},"Numbers",[36,628,629],{},"\"59.99\""," → ",[36,632,381],{},[621,634,635,87,638,630,641],{},[624,636,637],{},"Booleans",[36,639,640],{},"\"true\"",[36,642,643],{},"true",[621,645,646,649,650],{},[624,647,648],{},"Nulls",": empty cells → ",[36,651,652],{},"null",[621,654,655,87,658,661],{},[624,656,657],{},"Dates",[36,659,660],{},"\"2026-05-28\""," → ISO 8601 string or Date object",[15,663,664],{},"Without type casting, all JSON values are strings, which breaks API schemas and database validators.",[10,666,668],{"id":667},"common-pitfalls","Common Pitfalls",[618,670,671,684,697],{},[621,672,673,676,677,679,680,683],{},[624,674,675],{},"Inconsistent nesting depth"," — mixing ",[36,678,190],{}," and ",[36,681,682],{},"address"," as a column header creates ambiguity. Choose one pattern and stick to it.",[621,685,686,689,690,693,694,696],{},[624,687,688],{},"Missing array indices"," — ",[36,691,692],{},"orders.id"," without an index implies a single object, while ",[36,695,260],{}," explicitly creates an array. Be deliberate about which you need.",[621,698,699,702],{},[624,700,701],{},"Duplicate parent data"," — in one-to-many CSV, parent columns repeat across rows. The converter must deduplicate parent fields during grouping.",[10,704,706],{"id":705},"key-takeaways","Key Takeaways",[618,708,709,712,715,718,721,724],{},[621,710,711],{},"Flat CSV lacks hierarchy; nested JSON groups related data under common parents.",[621,713,714],{},"Dot-notation headers are the simplest way to define nesting structure in CSV.",[621,716,717],{},"One-to-many relationships require grouping rows by a parent key.",[621,719,720],{},"Always cast data types during conversion — CSV is all strings.",[621,722,723],{},"Choose a consistent strategy: dot notation for shallow nesting, multi-table for complex relationships.",[621,725,726],{},"Deduplicate parent fields when converting repeated rows into grouped arrays.",[10,728,730],{"id":729},"try-it-yourself","Try It Yourself",[15,732,733,734,739],{},"Convert your CSV data to nested JSON instantly with the ",[735,736,738],"a",{"href":737},"\u002Ftools\u002Fcsv-json","CSV to JSON Converter",".",[741,742,743],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}",{"title":34,"searchDepth":48,"depth":48,"links":745},[746,747,748,749,750,755,756,757,758],{"id":12,"depth":48,"text":13},{"id":23,"depth":48,"text":24},{"id":198,"depth":48,"text":199},{"id":283,"depth":48,"text":284},{"id":505,"depth":48,"text":506,"children":751},[752,753,754],{"id":510,"depth":54,"text":511},{"id":535,"depth":54,"text":536},{"id":553,"depth":54,"text":554},{"id":612,"depth":48,"text":613},{"id":667,"depth":48,"text":668},{"id":705,"depth":48,"text":706},{"id":729,"depth":48,"text":730},"2026-05-28","Transform flat spreadsheet data into hierarchical JSON structures for APIs and NoSQL databases.","md",{"immutable":763},true,"\u002Fguides\u002Fcsv-to-nested-json",{"title":5,"description":760},"guides\u002Fcsv-to-nested-json","cuo-nvGxsP8_vXIS05idFWicPcuoJvGDSVTYQAT71eg",1780401333243]