A report engine with a JSON data source: report templates without SQL¶
24 July 2026
Anyone who has ever adjusted a report template knows the picture: the template
contains SQL, the SQL reads columns such as I4201 or C2303, and changing the
report requires database knowledge, schema knowledge and a steady hand.
calServer V2 turns that around: the application supplies the data set, the
template only handles layout.
Data contracts instead of embedded SQL¶
Every report family has a defined, versioned data set:
| Contract | Report family |
|---|---|
calibration-certificate |
Calibration certificate |
inventory-datasheet |
Device data sheet |
order-document |
Order and delivery note |
repair-report |
Repair report |
location-report |
Location and loan report |
The fields are named the way they are named in the API: serial_number,
next_calibration_date, not I4201. Building a template means working in one
naming world instead of two. Custom fields are part of the data set and are
available without special handling.
Database-independent, because there is no SQL inside¶
A template without embedded SQL is no longer tied to a database schema. The same template renders identically on MySQL, PostgreSQL and Microsoft SQL Server. For installations migrating away from MySQL, "port all reports" drops off the migration list.
Nobody has to convert anything¶
Existing V1 templates keep running unchanged. calServer decides at generation
time which path applies: if the main JRXML contains no queryString, the JSON
data set is built, otherwise the classic JDBC path runs. A data_contract report
variable overrides the detection when you explicitly want something else,
including forcing jdbc.
That also settles an old failure mode: a V1 SQL template pointed at pure V2 records used to produce a technically "successful" but empty PDF. calServer now detects that constellation before rendering and aborts with a comprehensible message, visible in the report run log as well.
Designing templates against real data¶
The data set of a specific calibration can be fetched directly and used as a sample file in the report designer:
calServer also ships ready-made sample bundles per contract (for example
DAKKS-JSON-SAMPLE for the calibration certificate) as a starting point for your
own layouts.
The practical effect¶
Report changes move from the database into design work. Swapping a logo, adding a column or producing a bilingual certificate means changing the layout, not the query. And a report that works keeps working after a database change.
Guide and contract overview: Authoring V2 reports with a JSON data source. Background on the decision: ADR-009.