Forge Json

Flatten JSON in Node.js

Flatten nested API payloads into predictable path maps before adding a Node package, building a webhook test, or writing import code.

Paste your JSON → Get results instantly (no signup)

⚡ Instant resultsNo signupRuns in your browser
Try examples:

→ Flatten or nest keys in this JSON structure and flatten nested object.

{
"user": {
"name": "Alice",
"address": {
"city": "NYC",
"zip": "10001"
}
}
}
Output✓
1{
2  "user.name": "Alice",
3  "user.address.city": "NYC",
4  "user.address.zip": "10001"
5}

Love the result?

Use this exact pipeline in your app, backend, or LLM workflow.

No setup needed. Works with curl, Node, Python.

Uses example data. For edited input, copy from the playground.

Read integration guide

Works with:

  • Node.js scripts
  • Webhook tests
  • Express and API payloads
  • Fixture generation

Example: input → output

Flatten JSON in Node.js

Node.js projects often flatten JSON around API boundaries: webhook tests, import scripts, queue messages, logging, or test fixtures. A nested payload is natural for Express handlers and SDKs, but flat keys are easier to diff, print, export, and assert.

This page uses the same runner as the JSON flattener, with examples written for Node.js workflows and server-side payload debugging.

Node.js API payload example

Input:

const payload = {
  event: "invoice.paid",
  data: {
    customer: {
      id: "cus_123",
      email: "ada@example.com"
    },
    invoice: {
      total: 129,
      currency: "USD"
    }
  }
};

Flat output:

{
  "event": "invoice.paid",
  "data.customer.id": "cus_123",
  "data.customer.email": "ada@example.com",
  "data.invoice.total": 129,
  "data.invoice.currency": "USD"
}

That shape is useful in logs, snapshot tests, CSV exports, and contract-drift reports.

Node.js flatten helper

function flattenJson(value, prefix = "", output = {}) {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    output[prefix] = value;
    return output;
  }

  for (const [key, child] of Object.entries(value)) {
    const path = prefix ? `${prefix}.${key}` : key;
    flattenJson(child, path, output);
  }

  return output;
}

For package-based production code, compare your library's delimiter, array, and null behavior with this page before wiring it into a job.

Node.js vs browser JSON flattening

Use Node.js when flattening is part of an automated import, scheduled job, CLI, or backend handler. Use the online flattener when you need a quick payload inspection, a fixture, a bug-report sample, or an output contract before choosing a package.

For frontend-specific examples, use Flatten JSON in JavaScript. For REST and webhook payloads, use Flatten API Response JSON.

Common Node.js errors

  • Flattening request bodies without preserving the original nested payload for application logic.
  • Expanding arrays into many columns when logs only need the parent object.
  • Using a delimiter that conflicts with MongoDB, CSV headers, or existing source keys.
  • Snapshot-testing key order instead of key-value content.
  • Treating undefined as JSON; valid JSON only has null.

Frequently asked questions

How do I flatten JSON in Node.js?+

Use a recursive function or package that walks object entries and emits dotted path keys. Decide how arrays, null, and delimiter collisions should behave before production use.

When should Node.js code flatten API payloads?+

Flatten at boundaries such as logging, CSV export, snapshot tests, or contract reports. Keep the original nested payload for application logic.

Is undefined valid in flattened JSON?+

No. Valid JSON supports null, but not undefined. If a Node object contains undefined, serialize or normalize it before treating it as JSON.

Related tools

Read more on the blog

Advanced usage (optional)

Flatten / Nest

v1.0.0
Structure
objectarrayreversible

Description

Flatten / Nest

Convert between nested and flat object structures. Flatten deep objects into single-level key-value pairs, or nest flat keys back into hierarchical objects. Supports multiple key formats: delimiter-separated, camelCase, snake_case, PascalCase, and kebab-case.

Modes

Flatten

Convert nested objects into flat keys. Each nested path becomes part of the key name.

{ "user": { "name": "Alice" } }  →  { "user.name": "Alice" }

Nest

Convert flat keys back into nested objects by splitting on the delimiter or case boundaries.

{ "user.name": "Alice" }  →  { "user": { "name": "Alice" } }

Key Formats

Delimiter (default)

Join/split key segments with a character (default: .).

  • Flatten: user + name → user.name
  • Nest: user.name → user / name

camelCase

Join/split on uppercase letter boundaries.

  • Flatten: user + address + city → userAddressCity
  • Nest: userAddressCity → user / address / city

snake_case

Join/split on underscores.

  • Flatten: user + address + city → user_address_city
  • Nest: user_address_city → user / address / city

PascalCase

Same as camelCase but with uppercase first letter.

  • Flatten: user + name → UserName

kebab-case

Join/split on hyphens.

  • Flatten: user + name → user-name

Configuration

FieldTypeDefaultDescription
Modeenumflattenflatten or nest
Key Formatenumdelimiterdelimiter, camelCase, snake_case, PascalCase, or kebab-case
Delimiterstring.Character(s) used to join/split key segments (only for delimiter format)
Max Depthnumber0Maximum nesting depth to flatten (0 = unlimited)
Target Pathspath-picker[]Scope operation to specific paths only (empty = apply everywhere)

Use Cases

API Integration

  • Flatten for forms: Convert nested API responses to flat form field names
  • Nest for APIs: Convert flat form data back to nested API request bodies
  • Format conversion: Transform between dot-notation and camelCase conventions

Database Operations

  • MongoDB flattening: Flatten nested documents for tabular export
  • SQL mapping: Convert hierarchical JSON to flat column names for SQL insertion
  • Schema migration: Convert between naming conventions (snake_case ↔ camelCase)

Configuration Management

  • Environment variables: Flatten config objects to dot-notation for .env files
  • Depth limiting: Flatten only the first level while preserving deep structures

Configuration

NameTypeDefaultDescription
Modeenumflattenflatten: convert nested objects to flat keys. nest: convert flat keys back to nested objects. flatten nest
Key Formatenumdelimiterdelimiter: use a character to join/split. Others: camelCase, snake_case, PascalCase, kebab-case. delimiter camelCase snake_case PascalCase kebab-case
Delimiterstring.Character(s) used to join/split key segments (default is dot)
Max Depthnumber0Maximum nesting depth to flatten (0 = unlimited)
Target Pathspath-picker[]Scope operation to specific paths only (empty = apply everywhere)

Examples

AI Prompt
Flatten or nest keys in this JSON structure and flatten nested object.
{
"user": {
"name": "Alice",
"address": {
"city": "NYC",
"zip": "10001"
}
}
}
Output✓
1{
2  "user.name": "Alice",
3  "user.address.city": "NYC",
4  "user.address.zip": "10001"
5}
Config
Mode
flatten
Delimiter
.
Max Depth
0
Target Paths
all

API Usage

POST /api/v1/utilities/structure.flatten-nest
Example:
curl -X POST https://your-domain.com/api/v1/utilities/structure.flatten-nest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"primary":{"user":{"name":"Alice","address":{"city":"NYC","zip":"10001"}}}},"config":{"mode":"flatten","delimiter":".","maxDepth":0,"targetPaths":[]}}'
Response
1{
2  "user.name": "Alice",
3  "user.address.city": "NYC",
4  "user.address.zip": "10001"
5}