Forge Json
Get Started

Shape JSON Into a Known Target Structure

Extract a path, wrap a value, flatten one layer, or pluck a record when the next step expects a predictable JSON shape.

Paste your JSON → Get results instantly (no signup)

⚡ Instant resultsNo signupRuns in your browser
Try examples:

→ Unwrap this singleton array into its single value.

[
{
"username": "Morgan",
"email": "m@test.com"
}
]
Output✓
1{
2  "username": "Morgan",
3  "email": "m@test.com"
4}

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:

  • Known output schemas
  • Nested API response envelopes
  • Array wrappers and singleton records
  • Pipeline handoff shapes

Example: input → output

Shape JSON into a target structure

Input
{
  "data": {
    "user": {
      "name": "Morgan",
      "role": "admin"
    }
  }
}

Output
{
  "name": "Morgan",
  "role": "admin"
}

Shape JSON is for small, precise structure changes when the next step already expects a known shape. Use it to extract a nested path, ensure a value is an array, unwrap a singleton result, flatten one nested array layer, or pluck a record by index before another workflow step consumes the result.

This canonical tool page stays focused on direct shape operations. For a broader schema transformation workflow that combines extraction, normalization, validation, and downstream contract alignment, see the JSON schema transformation workflow pillar page.

When to use shape operations

Use Shape when the input is valid JSON but the wrapper is wrong for the next operation. A vendor SDK may wrap the object under data.user, a webhook replay may return a singleton array, or a table step may need the inner orders array instead of the whole response envelope.

Shape operations are intentionally narrow:

  • Extract path keeps one known nested branch.
  • Ensure array wraps a value so later steps can iterate safely.
  • Unwrap singleton turns a one-item array into the item itself.
  • Flatten array removes one level of nested arrays.
  • Pluck index selects a known item from an array.

Shape JSON vs schema transformation

Shape is one utility in a larger transformation toolkit. It changes the immediate wrapper or selected branch, but it does not describe a full multi-stage workflow by itself.

If the job is "take one provider schema and reconcile it with the internal schema we use everywhere else", use the JSON-to-JSON schema transformation page. That page covers field mapping, normalization, schema validation, and reusable transformation recipes.

Common mistakes

  • Using shape for broad cleanup. If the payload has nulls, whitespace, inconsistent casing, or noisy optional fields, run Clean JSON or Normalize JSON around the shape step.
  • Extracting the wrong branch. Check the path before running a pipeline. data.user and data.users[0] are different contracts.
  • Flattening too early. Flatten arrays only when the next step expects a single stream of items. Preserve parent context when downstream rules need it.
  • Plucking by unstable order. Index-based selection is safe for a known singleton or fixture, but risky when vendors can reorder arrays.

Frequently asked questions

What does the Shape JSON tool do?+

It changes the immediate structure of a JSON value: extract a nested path, ensure a value is an array, unwrap a singleton array, flatten one array layer, or pluck a known array index.

When should I use Shape instead of Normalize JSON?+

Use Shape when the wrapper or selected branch is wrong. Use Normalize JSON when records should share the same keys, defaults, or predictable schema across a collection.

Can Shape transform one whole schema into another?+

Shape can be one step in that workflow, but full schema transformation usually also needs field mapping, cleanup, normalization, and validation. Use the JSON-to-JSON schema transformation page for that broader workflow.

Does Shape upload my JSON?+

No. The tool runs in the browser like the other ForgeJSON utilities, so the shape operation can be tested without uploading a file to a server.

Common next steps

Related tools

Read more on the blog

Advanced usage (optional)

Shape

v1.0.0
Structure
objectarraydestructive

Description

Shape

Normalize JSON structure with five modes:

  • unwrap — Extract the value from a singleton array: [{obj}] → {obj}
  • ensureArray — Wrap non-arrays in an array: {obj} → [{obj}]
  • flatten — Flatten nested arrays with depth control: [[a],[b]] → [a,b]
  • pluck — Extract an element by array index: [a,b,c] → b
  • extract — Navigate to a nested path and return that value: {data:{user:{...}}} → {...}

All modes support Target Paths to scope the operation to specific locations within the document.

Configuration

NameTypeDefaultDescription
Modeenumunwrapunwrap: singleton array to value. ensureArray: wrap non-array in []. flatten: flatten nested arrays. pluck: extract by index. extract: extract nested path. unwrap ensureArray flatten pluck extract
Singleton OnlybooleantrueOnly unwrap single-element arrays (unwrap mode). When false, always takes the first element.
Flatten Depthnumber1How many levels of nested arrays to flatten (flatten mode). Use -1 for infinite depth.
Array Indexnumber0Index of element to extract (pluck mode). Supports negative indices (-1 = last).
PathstringDot-notation path to extract (extract mode). Example: data.user.name
Target Pathspath-picker[]Scope operation to specific paths only (empty = apply to root)

Examples

AI Prompt
Unwrap this singleton array into its single value.
[
{
"username": "Morgan",
"email": "m@test.com"
}
]
Output✓
1{
2  "username": "Morgan",
3  "email": "m@test.com"
4}
Config
Mode
unwrap
Singleton Only
ON

API Usage

POST /api/v1/utilities/structure.shape
Example:
curl -X POST https://your-domain.com/api/v1/utilities/structure.shape \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"primary":[{"username":"Morgan","email":"m@test.com"}]},"config":{"mode":"unwrap","singleton":true}}'
Response
1{
2  "username": "Morgan",
3  "email": "m@test.com"
4}