Working with JSON tables in Rust

Updated Oct 28, 2026

JSON file handling with automatic format detection and high-performance data operations.

Installation

cargo add --git https://github.com/datisthq/fairspec fairspec
cargo add serde_json

Getting Started

The JSON plugin provides:

load_json_table - Load JSON files into tables
save_json_table - Save tables to JSON files
JsonPlugin - Plugin for framework integration

For example:

use fairspec::fairspec_table::{LoadTableOptions, load_json_table};
use serde_json::json;

let resource = serde_json::from_value(json!({"data": "table.json"}))?;
let table = load_json_table(&resource, &LoadTableOptions::default())?;
// Standard JSON array of objects format

Unlike the other loaders, load_json_table returns Option<Table>: None when the data under the dialect's jsonPointer is not a table.

Basic Usage

Loading JSON Files

use fairspec::fairspec_table::{LoadTableOptions, load_json_table};
use serde_json::json;

let options = LoadTableOptions::default();

// Load from local file
let resource = serde_json::from_value(json!({"data": "data.json"}))?;
let table = load_json_table(&resource, &options)?;

// Load from remote URL
let resource = serde_json::from_value(json!({"data": "https://example.com/data.json"}))?;
let table = load_json_table(&resource, &options)?;

// Load multiple files (concatenated)
let resource = serde_json::from_value(json!({"data": ["file1.json", "file2.json"]}))?;
let table = load_json_table(&resource, &options)?;

Saving JSON Files

use fairspec::fairspec_table::{SaveTableOptions, save_json_table};
use serde_json::json;

// Save with default options
save_json_table(table.clone(), &SaveTableOptions {
    path: "output.json".into(),
    ..Default::default()
})?;

// Save with explicit format
save_json_table(table, &SaveTableOptions {
    path: "output.json".into(),
    file_dialect: Some(serde_json::from_value(json!({"format": "json"}))?),
    overwrite: Some(true),
    ..Default::default()
})?;

Standard Format

JSON tables use an array of objects format:

[
  { "id": 1, "name": "Alice", "age": 30 },
  { "id": 2, "name": "Bob", "age": 25 }
]

Advanced Features

JSON Pointer Extraction

Extract data from nested objects using jsonPointer:

use fairspec::fairspec_table::{LoadTableOptions, load_json_table};
use serde_json::json;

// Input: {"users": [{"id": 1, "name": "Alice"}]}
let resource = serde_json::from_value(json!({
    "data": "data.json",
    "fileDialect": {"format": "json", "jsonPointer": "/users"},
}))?;
let table = load_json_table(&resource, &LoadTableOptions::default())?;

Column Selection

Select specific columns using columnNames:

use fairspec::fairspec_table::{LoadTableOptions, load_json_table};
use serde_json::json;

// Only load specific columns
let resource = serde_json::from_value(json!({
    "data": "data.json",
    "fileDialect": {"format": "json", "columnNames": ["name", "age"]},
}))?;
let table = load_json_table(&resource, &LoadTableOptions::default())?;

Array Format Handling

Handle CSV-style array data with rowType: "array":

use fairspec::fairspec_table::{LoadTableOptions, load_json_table};
use serde_json::json;

// Input: [["id", "name"], [1, "Alice"], [2, "Bob"]]
let resource = serde_json::from_value(json!({
    "data": "data.json",
    "fileDialect": {"format": "json", "rowType": "array"},
}))?;
let table = load_json_table(&resource, &LoadTableOptions::default())?;

A row with more items than the header fails the load (validation reports the file as not loadable) instead of being cut to the header. In a multipart resource every part's header row must give part 1's column names, else a file/header error names the part; object rows have no header, so their parts are not compared and the columns are the union of their keys.

Saving with JSON Pointer

Wrap data in a nested structure when saving:

use fairspec::fairspec_table::{SaveTableOptions, save_json_table};
use serde_json::json;

// Output: {"users": [{"id": 1, "name": "Alice"}]}
save_json_table(table, &SaveTableOptions {
    path: "output.json".into(),
    file_dialect: Some(serde_json::from_value(json!({
        "format": "json",
        "jsonPointer": "/users",
    }))?),
    ..Default::default()
})?;