Can You Load a JSON File in Tableau?

Yes, you can absolutely load a JSON file into Tableau. It's a built-in feature designed to help you analyze data from web applications, APIs, and other modern data sources. This article will walk you through the exact steps for connecting to a JSON file, explain the most confusing part of the process - the “Select Schema Levels” dialog - and cover common troubleshooting tips for when things don’t go as planned.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

First, What Is a JSON File?

Before connecting one to Tableau, it helps to know what you’re working with. JSON (JavaScript Object Notation) is a lightweight, text-based format for storing and transporting data. If you’ve ever pulled data from a web API or looked at the configuration files for a software application, you’ve likely encountered JSON.

Think of it like a digital address book. Each contact is an object, and each piece of information about that contact (like name, email, and phone number) is a key-value pair.

A simple JSON object might look like this:

{
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "department": "Marketing"
}

JSON is popular because it's both easy for humans to read and for machines to parse. Many tools and platforms output data in this format, which is why Tableau includes a direct connector for it.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

How to Connect a JSON File in Tableau: A Step-by-Step Guide

Connecting your JSON file is straightforward. Follow these steps to get started.

Step 1: Open Tableau and Connect to Data

Launch Tableau Desktop. On the start screen, look at the “Connect” pane on the left side. Under the “To a File” heading, click on JSON File. If you don’t see it right away, you might need to click “More…” to see the full list of file types.

Step 2: Select Your File

An explorer window will open. Navigate to the location of your JSON file on your computer, select it, and click “Open.”

Step 3: Select Your Schema Levels

This is the most critical - and often most confusing - step. Once you select your file, Tableau will analyze its structure and present you with a dialog box titled “Select Schema Levels.”

Here, you need to tell Tableau which parts of the hierarchical JSON data you want to turn into rows and columns. We’ll cover this in much more detail in the next section because getting this right is the key to working with JSON data successfully.

Step 4: Go to the Worksheet

Once you’ve selected your schema levels, Tableau will load the data and display a preview. It will show you the columns it generated based on your selection. If it looks correct, click on a sheet tab at the bottom (e.g., “Sheet 1”) to begin building your visualizations.

The Most Important Step: Understanding the 'Select Schema Levels' Dialog Box

When Tableau opens a JSON file, it can't just assume how you want to structure it. JSON files are often "nested," with data inside of other data, like sets of Russian dolls.

For example, imagine a JSON file containing customer order data. You might have a top-level object for each "Order," but nested inside each order, you could have a "Customer" object and an array of "Products."

The "Select Schema Levels" dialog box is Tableau's way of asking: "What is the main subject you want to analyze?" Your choice determines what becomes a row in your data source.

How to Choose the Right Schema Level

Let's use our order data example. The schema might look like this in the dialog box:

• Order Details
• Customer Information
• Line Items

You have to decide on your "level of detail" or the focus of your analysis:

• If you select the top level ("Order Details"): Each row in your dataset would represent a single order. You’d get columns for OrderID, OrderDate, and TotalAmount. Columns related to nested data like CustomerName and ProductName would also be flattened into the same row. However, if an order has multiple products, Tableau will duplicate the order and customer information for each product, which might be what you want.
• If you select "Line Items": Each row would represent a single product within an order. This is the most granular level. You’d get columns like ProductID, ProductName, Quantity, and Price, along with associated information like the OrderID it belongs to. This is ideal if you want to analyze product sales performance.
• If you select "Customer Information": Each row would represent a customer. Any order they made would be associated with that single customer row.

Your goal is to pick the schema level that corresponds to the fundamental unit of your analysis. If you want to analyze sales of individual products, choose the level that defines a product. If you're looking at overall orders, choose the order level.

Don’t be afraid to experiment. You can always go back, connect to the same file again, and select a different schema level to create a new data source for a different type of analysis.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Common Problems and How to Fix Them

Sometimes, loading JSON files into Tableau doesn't go smoothly. Here are some of the most common issues and what to do about them.

Problem: Your JSON is Deeply Nested or Complex

Tableau's connector can handle basic nesting, but it can struggle with data that is many layers deep or has a highly irregular structure. When this happens, the schema selection can become unwieldy, or the resulting table in Tableau may not make sense.

Solution: Pre-process and flatten your JSON. For complex files, it’s often better to simplify - or "flatten" - the JSON before you load it. Flattening turns nested data into a simpler, non-nested structure where each nested key becomes part of a new key.

You can use free online JSON-to-CSV converters or data preparation tools. If you're comfortable with code, a simple Python script using the pandas library can flatten even the most complicated JSONs into a clean, table-like format perfect for Tableau.

Problem: The File Won't Load at All

If you select your file and Tableau immediately gives you an error, it’s likely that the file is not a valid JSON.

Solution: Validate your JSON file. A single missing comma, bracket, or curly brace can make the entire file unreadable. Copy and paste the contents of your file into a free online "JSON validator" tool. These tools will scan your file and pinpoint the exact location of any syntax errors so you can fix them.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Problem: The Columns Seem Wrong or Don't Match Your Expectations

This is the most common issue. You pick a schema level, load the data, and find that the columns are missing key information or don't seem to represent what you wanted to analyze.

Solution: Re-select your schema level. This almost always means you chose the wrong schema level during the connection process. Close the data source tab, reconnect to the same JSON file from the start menu, and carefully examine the "Select Schema Levels" dialog again. Try picking a "child" or "parent" level relative to your first choice to see if it produces a better result.

Remember, your selection defines what constitutes a single row. Ask yourself, "What should one row in this table represent?" and pick the schema level that matches your answer.

Best Practices for Working with JSON in Tableau

To make your life easier, follow these simple tips when working with JSON data.

• Start with clarity. Before connecting, take a moment to understand what you want to achieve. What questions are you trying to answer? Knowing this helps you choose the correct schema level from the start.
• Test with a small sample. If you have a huge JSON file, try loading a small snippet of it first. This allows you to quickly experiment with schema levels without waiting for a massive file to parse.
• Flatten complex structures first. If your JSON looks like a tangled spiderweb of nested objects and arrays, taking a few minutes to flatten it beforehand can save you an hour of wrestling with it in Tableau.
• Don't forget the Data Interpreter. Once your data is loaded into the data source pane, try turning on Tableau’s “Data Interpreter.” It’s designed to automatically clean up messy data and can sometimes work wonders on JSON exports.

Final Thoughts

Connecting a JSON file to Tableau is absolutely possible and opens up a wide world of data from modern web and app sources. Success hinges on understanding its nested structure and thoughtfully choosing the right schema level that aligns with your analytical goals. While dealing with complex files can sometimes require a bit of prep work, it's a powerful and flexible way to visualize your data.

We know that wrangling different file formats and manually structuring data schemas can be a major friction point, even for seasoned analysts using powerful tools. That experience is a big reason why we built Graphed. Our approach allows you to connect your data sources - whether from an API, a SaaS platform, or a file - and have our AI handle the interpretation for you. Instead of worrying about schema levels, you can simply use natural language to ask questions, build dashboards, and get the insights you need instantly.