Posted on by RESERVE

Why JSONL Matters for FRED Data

When most people think about working with FRED data, they think in terms of CSV files or API JSON responses. CSV files make immediate sense to the desktop economist: download the series, open it in Excel, chart it, regress it, annotate it, and move on. Plain JSON serves a different audience. It is the natural format for applications, APIs, and software systems that need structured data with fields, arrays, and metadata. Both formats are familiar, both are widely supported, and both are perfectly adequate for small-scale analysis. But once you begin building downstream pipelines around economic observations — particularly pipelines that transform, stream, enrich, or continuously ingest data — the limitations of those formats begin to show.

This is where JSONL becomes interesting.

What is JSONL?

JSONL stands for JSON Lines.

Instead of storing all records inside a single JSON array, JSONL stores one JSON object per line.

For example:

{"date":"2024-01-01","value":"100.2"}
{"date":"2024-02-01","value":"101.1"}
{"date":"2024-03-01","value":"101.8"}

Each line is independently valid JSON.

That small design difference has major implications for data engineering workflows.

JSON vs JSONL

Traditional JSON usually looks like this:

{
  "observations": [
    {"date":"2024-01-01","value":"100.2"},
    {"date":"2024-02-01","value":"101.1"},
    {"date":"2024-03-01","value":"101.8"}
  ]
}

Traditional JSON encourages you to think in terms of documents. A FRED response becomes one large object containing metadata, arrays, nested structures, and observation collections. Before a downstream process can begin its work, the entire payload typically needs to be materialized in memory and parsed as a complete unit.

JSONL encourages a different mental model. Instead of one document containing observations, the observations themselves become the primary unit of computation. Each line can be read independently, transformed independently, validated independently, and streamed independently. The data stops behaving like a static export and starts behaving like a sequence of economic events flowing through a pipeline.

That distinction matters enormously for time-series systems.

Economic observations are naturally append-oriented. New CPI values arrive. New unemployment figures arrive. GDP revisions arrive. Rarely do we need to reinterpret the entire historical universe every time a new observation appears. More commonly, we want to process the newest data incrementally while preserving provenance and transformation history downstream.

CSV works extremely well right up until the moment your workflow becomes more complicated than a spreadsheet. A single economic series with a date column and a value column is simple. But once you start combining multiple series, revision histories, release metadata, transformations, or provenance tracking, the format starts showing its age. Important context often ends up scattered across filenames, sidecar documents, README notes, or pipeline assumptions rather than traveling with the observations themselves.

Traditional JSON solves some of those problems, but introduces another. The data becomes hierarchical and application-centric rather than stream-centric. Appending a single new observation often means rewriting an entire array. Distributed processing becomes less elegant. Line-oriented tooling becomes harder to leverage.

JSONL occupies a remarkably useful middle ground. It preserves the self-describing nature of JSON while remaining operationally compatible with streaming systems, append-only workflows, Unix pipelines, and distributed analytical tooling.

That alignment becomes especially important inside RESERVE.

Within RESERVE, FRED observations are not treated merely as downloadable datasets. They are treated as composable records that can move through transformation pipelines. Once observations are emitted as JSONL, the output becomes naturally compatible with downstream operators:

reserve fred observations CPIAUCSL --format jsonl

At that point, transforms stop feeling like post-processing steps attached to static files and begin behaving more like streaming operators acting on a flow of economic observations.

A rolling average transform no longer needs to conceptualize itself as “opening a file.” It can instead consume observations incrementally as they arrive:

reserve fred observations FEDFUNDS --format jsonl \
  | reserve transform moving-average --window 12

This is ultimately why JSONL matters for FRED data. The format aligns with the actual shape of economic time-series workflows. Observations arrive sequentially. Pipelines process sequentially. Transformations operate sequentially. JSONL simply removes unnecessary structural friction between the data and the systems operating on it.

Consumers as First Class Citizens

RESERVE was designed and developed to democratize access to FRED data. One key design goal was to treat humans, other programs, and LLM-based agents as first-class consumers.

RESERVE’s tabular formats and charting functions target human consumers. CSV targets desktop tools and relational data stores. JSON targets API-driven applications and LLMs, while JSONL caters to data pipelines and streaming-oriented applications.

A naysayer might ask, “So what? Any program or script can reformat data!”

There is an important nuance.

Accessing FRED data requires consumers to adhere to the usage requirements of the underlying sources. A FRED source generally falls into one of three categories:

  • Public Domain: Citation Requested
  • Copyrighted: Citation Required
  • Copyrighted: Contact Source (Permission is Required)

As a software program, RESERVE checks source-usage requirements during retrieval and carries the appropriate disclosure information throughout its processing, including into its various output formats.

In the example below, GDP is a public-domain data series for which citation is requested:

reserve obs latest gdp --format jsonl
{"series_id":"GDP","date":"2026-04-01","value":32486.066,"value_raw":"32486.066","citation_text":"Source: Bureau of Economic Analysis via FRED"}

Compliance with FRED’s source-usage requirements involves more than using a standard library to flip data from one output format to another. The disclosure must remain semantically attached to the data as it moves through RESERVE’s processing pipeline and into the format requested by the consumer.

This behavior was deliberately architected into RESERVE. Its validation is also part of the automated test suite and is revalidated with every release.

Summary

Modern software can generally convert data back and forth between formats. But not having the right format at the point of consumption creates inefficiencies, unnecessary processing, and performance headwinds. This is particularly relevant when working with large datasets, such as those potentially delivered by the FRED API.

RESERVE treats all consumers—and the formats they consume—as first-class citizens. Humans can work with tables and charts. Desktop tools and databases can consume CSV. Applications and LLMs can consume JSON. Data pipelines can consume JSONL.

Moreover, RESERVE recognizes that the format is only part of the contract. Source disclosure and usage requirements must travel with the data. By preserving that information across formats, RESERVE delivers data that is not only convenient to consume, but also carries the context necessary to use it responsibly.