Introduction

TensorFlow does not treat arbitrary JSON as a first-class training format the way it treats TFRecord or image folders. In practice, you usually read JSON with normal Python tools, convert the fields into tensors, and then build a tf.data.Dataset. The best approach depends on whether the file is a single JSON array or newline-delimited JSON where each line is its own object.

Read a Regular JSON File With Python First

If the file is a normal JSON document, the simplest path is to load it with Python’s json module and then convert the result into tensors.

Example file named samples.json:

1[
2  {"x": [1.0, 2.0], "label": 0},
3  {"x": [3.0, 4.0], "label": 1}
4]

Read it like this:

1import json
2import tensorflow as tf
3
4with open("samples.json", "r", encoding="utf-8") as f:
5    records = json.load(f)
6
7features = [item["x"] for item in records]
8labels = [item["label"] for item in records]
9
10ds = tf.data.Dataset.from_tensor_slices((features, labels))
11
12for x, y in ds:
13    print(x.numpy(), y.numpy())

This is often the clearest choice for small and medium datasets.

Convert JSON Fields Into the Shapes Your Model Expects

JSON values are flexible, but TensorFlow likes explicit shapes and dtypes. If a model expects float32 features and integer labels, convert them deliberately.

1import json
2import tensorflow as tf
3
4with open("samples.json", "r", encoding="utf-8") as f:
5    records = json.load(f)
6
7features = tf.constant([item["x"] for item in records], dtype=tf.float32)
8labels = tf.constant([item["label"] for item in records], dtype=tf.int32)
9
10ds = tf.data.Dataset.from_tensor_slices((features, labels)).batch(2)
11
12for batch_x, batch_y in ds:
13    print(batch_x)
14    print(batch_y)

Being explicit here prevents a lot of downstream shape and dtype confusion.

Use TextLineDataset for Newline-Delimited JSON

Large pipelines often store data as one JSON object per line, sometimes called JSONL or NDJSON. That format works better with streaming input because you can read line by line.

Example file:

{"x": [1.0, 2.0], "label": 0}
{"x": [3.0, 4.0], "label": 1}

A practical TensorFlow pipeline looks like this:

1import json
2import tensorflow as tf
3
4def parse_line(line):
5    def _parse(raw):
6        obj = json.loads(raw.decode("utf-8"))
7        return obj["x"], obj["label"]
8
9    x, y = tf.py_function(
10        _parse,
11        [line],
12        Tout=[tf.float32, tf.int32]
13    )
14    x.set_shape([2])
15    y.set_shape([])
16    return x, y
17
18ds = tf.data.TextLineDataset("samples.jsonl")
19ds = ds.map(parse_line).batch(2)
20
21for batch_x, batch_y in ds:
22    print(batch_x)
23    print(batch_y)

This approach keeps memory use lower for large line-based datasets because the whole file does not need to be loaded into a Python list first.

Choose the Right Pattern for the File Shape

A good rule is:

• use json.load for a regular JSON document
• use TextLineDataset for one-object-per-line files
• use TFRecord instead of JSON if the dataset is very large and performance matters

TensorFlow can absolutely work with JSON, but JSON is often more of an interchange format than a high-performance training format.

Handle Nested or Irregular Data Carefully

If the JSON contains nested objects, variable-length lists, or missing fields, convert it into a consistent tensor-friendly structure before training.

For example, if every record has a variable number of token IDs, you may need padding or ragged tensors instead of a plain dense tensor. If fields are optional, fill defaults during parsing so later dataset steps see a stable structure.

The main goal is to transform flexible JSON into a predictable tensor schema.

Build a Real Input Pipeline

Once the data is parsed, you can use normal tf.data optimizations:

1ds = (
2    ds
3    .shuffle(1000)
4    .batch(32)
5    .prefetch(tf.data.AUTOTUNE)
6)

Those operations happen after parsing. The cleaner your conversion step is, the easier the rest of the input pipeline becomes.

Common Pitfalls

The most common mistake is expecting TensorFlow to parse arbitrary JSON automatically without a conversion step. Another is forgetting to set shapes after tf.py_function, which leaves TensorFlow with too little static shape information. Developers also mix numeric and string types in JSON and then run into dtype errors later. Loading a huge JSON array into memory can be inefficient, so line-delimited JSON plus TextLineDataset is often better for large files. If performance becomes critical, JSON may simply be the wrong storage format for the training pipeline.

Summary

• TensorFlow usually reads JSON by combining Python parsing with tf.data.
• Use json.load for regular JSON documents and TextLineDataset for JSONL files.
• Convert fields into explicit TensorFlow dtypes and shapes early.
• Call set_shape after tf.py_function when needed.
• Use padding or ragged tensors for variable-length data.
• Consider TFRecord if JSON parsing becomes a training bottleneck.