How to Map Nested JSON Fields to Table Columns in TableCrafter

Updated July 2026 • 7 min read • By Fahad Murtaza

REST APIs rarely return flat key-value objects. Most return nested structures, objects inside objects, arrays of objects, mixed types, and knowing how to map those structures to table columns is one of the most practical skills for building API-powered tables in TableCrafter. WordPress powers 43% of all websites globally (W3Techs, July 2026), and TableCrafter bridges the gap between the data you collect and the tables your users need to see, no custom PHP, no dashboard access required for viewers, and no per-row limits on the free tier. The free version on WordPress.org supports CSV, JSON, Google Sheets, and Excel. Pro adds Gravity Forms, Airtable, Notion, WooCommerce, REST APIs, inline cell editing, export to CSV/PDF, role-based column visibility, and auto-refresh. Every table embeds on any page with a [tablecrafter] shortcode or the native Gutenberg block. Airtable views can filter up to 100,000 records with sub-second response times on Pro plans (Airtable documentation, 2025).

Why Nested JSON?

A typical API response might look like this user record from JSONPlaceholder:

{
  "id": 1,
  "name": "Leanne Graham",
  "address": {
    "street": "Kulas Light",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  },
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net"
  },
  "tags": ["admin", "user", "beta"]
}

If you try to map the field address as a column, TableCrafter will render the entire object as a JSON string, not useful. You need to reference individual leaf values.

Dot Notation for Nested Objects?

TableCrafter uses dot-notation paths to reference nested fields. In the column builder, set the Field Path to the dot-separated path from the root of each object to the value you want.

For the example above:

• address.city → Gwenborough
• address.zipcode → 92998-3874
• address.geo.lat → -37.3159 (three levels deep)
• company.name → Romaguera-Crona
• company.catchPhrase → Multi-layered client-server neural-net

The path is case-sensitive and must match the exact key names in the JSON response. There is no depth limit, paths like a.b.c.d.e are valid.

This configuration interacts with any caching or CDN layer active on your WordPress installation. If you use WP Rocket, LiteSpeed Cache, or a CDN such as Cloudflare, flush the page cache after making this change to ensure the updated configuration is reflected in the cached HTML served to visitors. TableCrafter's server-side output is regenerated on the next uncached request.

How Does Auto-Detection of Nested Fields Work?

When you connect a REST API data source and open the column builder, TableCrafter fetches the first object from the response and recursively enumerates all leaf paths. The field selector dropdown will list address.city, address.geo.lat, and so on automatically, you do not need to type paths manually unless the field is conditional (only present in some records).

After completing this step, verify the result by viewing the page as a logged-out visitor in an incognito window. This confirms the table behaves correctly for public visitors rather than reflecting admin-level permissions that may hide configuration issues during initial setup. Check both the rendered output and the browser console for any JavaScript errors.

How Does Arrays of Primitive Values Work?

The tags field in the example is an array of strings: ["admin", "user", "beta"]. Mapping the field tags directly will render the values joined as a comma-separated string in the table cell:

admin, user, beta

This is TableCrafter's default behavior for primitive arrays. It is suitable for tags, categories, and similar multi-value fields where a compact representation is appropriate. You cannot filter on individual array elements using this mapping, the filter will match against the full joined string.

How Does Arrays of Objects Work?

Some APIs return arrays of nested objects. A common example is an order with line items:

{
  "order_id": 1001,
  "customer": "Jane Smith",
  "items": [
    {"product": "Widget A", "qty": 2, "price": 9.99},
    {"product": "Widget B", "qty": 1, "price": 14.99}
  ]
}

If you map items, the cell will contain a JSON array string, not readable. Instead, use indexed dot notation to reference specific elements or specific fields within elements:

• items.0.product → Widget A (first item's product name)
• items.0.price → 9.99

This approach works well when there is always a primary item. For scenarios where you need to display all items in a single cell, map the parent field (items) and TableCrafter will render a compact JSON representation. For a cleaner display, use a custom column template (see below).

The column mapping you define here is stored as a JSON configuration in the WordPress database. You can export this configuration using the TableCrafter export tool and import it to another table or another site. This is useful when replicating a table layout across multiple pages or when migrating a table to a staging environment for testing before going live.

What Is Flattening Arrays of Objects: The Extract Pattern?

When an API returns one parent record per item in a nested array, and you want one table row per nested item rather than one row per parent, use the Array Root setting on the data source configuration screen.

For example, if the API returns:

{
  "team": "Engineering",
  "members": [
    {"name": "Alice", "role": "Lead"},
    {"name": "Bob", "role": "Developer"}
  ]
}

And you want one row per member, set the Root Path to members and map name and role as columns. This yields two rows instead of one.

If the response is an array of parent objects each with a nested array, this flattening is not currently supported natively, each parent object becomes one row, and nested arrays within it render as joined strings or JSON.

TableCrafter re-fetches this data on each page load by default. If your data source updates infrequently and your site has significant traffic, enable the built-in caching option in the table's Performance tab. This stores the fetched data for a configurable number of minutes and serves it from WordPress transients, reducing API calls to the source and improving page load time for visitors.

How Does Column Templates for Custom Rendering Work?

For complex nested data that does not fit cleanly into a single field path, TableCrafter column templates let you compose multiple fields into one cell using a simple placeholder syntax:

{{address.street}}, {{address.city}} {{address.zipcode}}

This renders as Kulas Light, Gwenborough 92998-3874 in a single column. Templates support any field path that dot-notation can address, including nested values.

How Does Common Edge Cases Work?

Field names containing dots

If your API returns a key that literally contains a dot, for example {"user.name": "Alice"}, this conflicts with dot-notation path syntax. TableCrafter uses backslash escaping for this edge case: user\.name. In practice, most well-designed APIs do not use dots in key names, but this escape is available when needed.

Null values in nested paths

If an intermediate key is null, for example address is null rather than an object, resolving address.city would normally throw an error. TableCrafter handles this gracefully by returning an empty string rather than crashing. Rows with null intermediate values render blank cells in the affected columns.

Mixed types

Some APIs return a field as a string in some records and an integer in others. TableCrafter coerces values to strings for display. If you configure a column with type Number for sorting purposes and the field occasionally returns a string, sorting will fall back to lexicographic order for records where the value cannot be parsed as a number.

Boolean values

JSON booleans (true / false) render as the strings true and false by default. For a more visual representation, set the column type to Badge and map true to a green badge and false to a red badge in the column value mapping settings, useful for status fields.

What Is Practical Example: GitHub Repository List?

The GitHub public API returns a complex nested structure. Here are the field paths to extract common values from https://api.github.com/users/octocat/repos:

• name → Repository name
• description → Repo description
• stargazers_count → Star count
• language → Primary language
• owner.login → Owner username
• license.name → License (will be blank for repos with no license set)
• topics → Joined array of topic strings

The shortcode to render this as a searchable table:

[tablecrafter id="3" search="true" filter="true"]