JRDL Documentation

Introduction

What is JRDL?

JRDL (JSON Report Definition Language) is a declarative JSON format for defining custom data reports in Papereg. A single JRDL document fully describes:

• Data sources — which forms to pull data from, with field mappings that translate form field names to report-level keys
• Layout components — summary cards, charts, and tables that visualize the data
• Filter configuration — default date ranges and user-configurable filter options

JRDL is the portable format used for exporting and importing custom reports between workspaces.

What are Custom Reports?

Custom Reports let you build your own dashboards by pulling data from one or more forms in your workspace, applying aggregations (count, sum, average, etc.), and displaying results as summary cards, charts (bar, line, doughnut, pie, radar), and sortable tables.

Relationship to Preset Reports

Papereg ships with Preset Reports tied to industry templates (HR, Healthcare, Construction, etc.). Custom Reports extend this by letting you build any report from any form data — using the visual builder or raw JRDL JSON.

Quick Start

Minimal Example

The simplest JRDL document counts submissions from a single form:

{
"version": "1.0",
"sources": [
{
  "alias": "intake",
  "form_name": "Patient Intake",
  "field_mappings": {
    "patient_name": "full_name"
  }
}
],
"layout": {
"summary_cards": [
  {
    "id": "card_total",
    "title": "Total Patients",
    "source": "intake",
    "aggregation": "count",
    "color": "primary"
  }
],
"charts": [],
"tables": []
},
"filters": {
"default_date_range": "30d"
}
}

Builder vs JSON

There are two ways to create custom reports:

Export → Edit → Import

1. Create a report using the visual builder
2. Export it as JSON via the UI or GET /api/v1/custom-reports/:uid/export
3. Edit the JSON file with your preferred editor
4. Import back via the UI or POST /api/v1/custom-reports/import

Schema Reference

A JRDL document is a JSON object with the following top-level keys:

{
"version": "1.0",
"metadata": { ... },    // export only
"sources": [ ... ],
"layout": {
"summary_cards": [ ... ],
"charts": [ ... ],
"tables": [ ... ]
},
"filters": { ... }
}

Sources

Each source links a report to a form and defines how form fields map to report-level keys.

* For import: at least one of form_uid or form_name is needed for automatic form matching.

{
"alias": "intake",
"form_uid": "AZzVeQVRe3aLCwHt5yHaRA",
"form_name": "Patient Intake",
"field_mappings": {
"patient_name": "full_name",
"age": "patient_age",
"visit_date": "date_of_visit",
"department": "department"
},
"position": 0
}

Summary Cards

Summary cards display a single aggregated metric as a large number with a title, icon, and color.

{
"id": "card_avg_age",
"title": "Average Age",
"source": "intake",
"aggregation": "average",
"field": "age",
"color": "secondary",
"icon": "hero-user",
"format": "decimal:1"
}

Charts

Charts visualize data from a source. Each chart operates in one of two modes: distribution (categorical breakdown) or time series (temporal trend).

Distribution Mode

Groups data by a categorical field. Works with all chart types.

{
"id": "chart_dept",
"title": "Patients by Department",
"source": "intake",
"type": "doughnut",
"width": "half",
"group_by": "department"
}

Time Series Mode

Groups data by time periods. Best with line or bar charts.

{
"id": "chart_trend",
"title": "Patient Volume Over Time",
"source": "intake",
"type": "line",
"width": "full",
"x_axis": {
"field": "_submitted_at",
"group_by": "month"
},
"y_axis": {
"aggregation": "count"
}
}

Tables

Tables display individual submission rows with selected columns, sorting, and pagination.

{
"id": "table_recent",
"title": "Recent Patients",
"source": "intake",
"columns": ["patient_name", "age", "department", "visit_date"],
"sort": {
"field": "visit_date",
"direction": "desc"
},
"limit": 50,
"show_submission_link": true
}

Filters

The filters object configures date range defaults and which filter controls are available to users.

{
"default_date_range": "30d",
"allow_date_range": true,
"allow_custom_dates": true,
"additional_filters": [
{ "field": "department", "label": "Department" }
]
}

Validation Rules

Every JRDL definition is validated before saving. The validator checks:

• Version must be "1.0"
• Source aliases must be unique, start with a letter, and contain only lowercase letters, digits, and underscores
• Layout component sources must reference a defined source alias
• Charts must have either group_by (distribution) or x_axis (time series), not both
• Field required for sum, average, min, max, distinct_count aggregations
• Format strings must match pattern: base or base:N (e.g., "decimal:2")
• Table limit must be a positive integer, max 1000

Error Format

Validation errors are returned as a list of path + message objects:

{
"errors": [
{ "path": "version", "message": "is required" },
{ "path": "sources[0].alias", "message": "must start with a letter and contain only lowercase letters, digits, underscores" },
{ "path": "layout.charts[0].type", "message": "must be one of: bar, line, doughnut, pie, radar" },
{ "path": "layout.summary_cards[1].source", "message": "references unknown source alias \"unknown_src\"" }
]
}

Export / Import

Export Format

When you export a report, the JRDL definition is enriched with a metadata block and source form identifiers:

{
"metadata": {
"name": "Monthly KPI Dashboard",
"description": "Tracks key metrics across intake and feedback forms",
"created_by": "admin@example.com",
"created_at": "2025-06-01T12:00:00Z",
"workspace_origin": "My Workspace"
},
"sources": [
{
  "alias": "intake",
  "form_uid": "AZzVeQVRe3aLCwHt5yHaRA",
  "form_name": "Patient Intake",
  "field_mappings": { ... }
}
]
}

Import Flow

1. Parse JSON and validate against the JRDL v1.0 schema
2. Match sources to forms: first by form_uid, then by form_name
3. Handle missing forms based on import mode
4. Create report as draft (not published) with " (Imported)" suffix

Cross-Workspace Portability

JRDL definitions are workspace-agnostic. Source matching by form_name enables sharing between workspaces with similarly named forms. This makes JRDL ideal for:

• Sharing report templates across teams or organizations
• Bundling reports with workspace presets
• Version-controlling report definitions in Git

Aggregation Functions

Chart Types & Rendering

Value Formatting

The format field on summary cards controls how the computed value is displayed.

nil values always display as — regardless of format.

Execution Pipeline

When a report is executed (viewed or exported), the engine processes data in this order:

1. Source Loading — For each source, look up the form by ID, resolve field mappings to field IDs, and query submissions
2. Date Filtering — Filter submissions where submitted_at falls between start_date and end_date
3. Status Filtering — Only "submitted" and "approved" status submissions are included
4. Field Mapping — Transform each row using: report_key → form_field_name → field_id → submission_data value
5. Summary Card Computation — Apply aggregation functions to the mapped data per source
6. Chart Building — Group data and build Chart.js-compatible config objects
7. Table Building — Select columns, apply sorting and limits
8. Warning Collection — Collect warnings for missing forms, missing fields, and non-numeric aggregation attempts

Result Structure

{
"summary_cards": [ { "id": "...", "title": "...", "value": 42 }, ... ],
"charts": [ { "id": "...", "title": "...", "chart_config": { ... } }, ... ],
"tables": [ { "id": "...", "title": "...", "rows": [...], "columns": [...] }, ... ],
"warnings": [ "Source 'feedback': form not found" ],
"source_data": { "intake": { "row_count": 150 } },
"date_filter_label": "Last 30 days"
}

API Endpoints

All endpoints require a valid API token. See API Documentation for authentication details.

Plan Limits

Free plan does not include custom reports. Upgrade to Starter or above to get started.

Permissions

Permissions can be customized per role in Settings → Permissions. Owner always has all permissions.

Full Example

A complete JRDL document with 2 sources, 3 summary cards, 2 charts, and 1 table:

{
"version": "1.0",

"sources": [
{
  "alias": "intake",
  "form_name": "Patient Intake",
  "field_mappings": {
    "patient_name": "full_name",
    "age": "patient_age",
    "visit_date": "date_of_visit",
    "department": "department"
  },
  "position": 0
},
{
  "alias": "feedback",
  "form_name": "Patient Feedback",
  "field_mappings": {
    "rating": "satisfaction_rating",
    "comment": "additional_comments"
  },
  "position": 1
}
],

"filters": {
"default_date_range": "30d",
"allow_date_range": true,
"allow_custom_dates": true
},

"layout": {
"summary_cards": [
  {
    "id": "card_total",
    "title": "Total Patients",
    "source": "intake",
    "aggregation": "count",
    "color": "primary",
    "icon": "hero-users"
  },
  {
    "id": "card_avg_age",
    "title": "Average Age",
    "source": "intake",
    "aggregation": "average",
    "field": "age",
    "color": "secondary",
    "format": "decimal:1"
  },
  {
    "id": "card_avg_rating",
    "title": "Avg Satisfaction",
    "source": "feedback",
    "aggregation": "average",
    "field": "rating",
    "color": "success",
    "format": "decimal:1"
  }
],

"charts": [
  {
    "id": "chart_trend",
    "title": "Patient Volume Over Time",
    "source": "intake",
    "type": "line",
    "width": "full",
    "x_axis": {
      "field": "_submitted_at",
      "group_by": "month"
    },
    "y_axis": {
      "aggregation": "count"
    }
  },
  {
    "id": "chart_dept",
    "title": "Patients by Department",
    "source": "intake",
    "type": "doughnut",
    "width": "half",
    "group_by": "department"
  }
],

"tables": [
  {
    "id": "table_recent",
    "title": "Recent Patients",
    "source": "intake",
    "columns": ["patient_name", "age", "department", "visit_date"],
    "sort": {
      "field": "visit_date",
      "direction": "desc"
    },
    "limit": 50,
    "show_submission_link": true
  }
]
}
}

Glossary