jsreports JSON Report Schema
Report
Describes the JSON report definition format used by jsreports. The root element in the JSON structure is a Report, containing sections that in turn contain elements.
{
"title": "Project Detail by Client and Task",
"id": "jsreports-demo-grouping",
"default_format": "html",
"version": "1.2.20",
"page": Page,
"filters": [ Filter ],
"inputs": [ Input ],
"header": Section,
"body": BodySection,
"footer": Section,
"page_header": Section,
"page_footer": Section,
"type": "hierarchical"
}| Property | Description |
|---|---|
| pageobject | Defines the print page setup for the report |
| headerobject | A Section representing the report header, which is shown once at the top of the report |
| bodyobject | A BodySection representing the report body |
| footerobject | A Section representing the report footer, which is shown once at the bottom of the report |
| idstring | Report ID |
| versionstring | Version of jsreports used to create this report (when created by the designer or report builder API) |
| default_formatstring | Not currently usedMust be: "html" |
| titlestring | Title of report to be shown to user, for use by plugins listing available reports |
| filtersarray | Filters to apply to the report's top-level data source; only matching records will appear in the report |
| inputsarray | User-facing inputs to display in the report toolbar, for supplying parameters to the report at runtime |
Page
Defines the print page setup for the report
{
"units": "inches",
"paper_size": {
"name": "Letter",
"inches": [
"8.5",
"11"
],
"mm": [
"216",
"279"
],
"id": "letter"
},
"margins": {
"top": 0.5,
"left": 0.5,
"right": 0.5,
"bottom": 0.5
}
}| Property | Description |
|---|---|
| unitsstring | The units to use for page dimensions and positioning elementsOne of: "mm", "inches" |
| paper_sizeobject | Defines the size of the paper when outputting to paged media (e.g. PDF). Either "inches" or "mm" property is required, matching the value of the page.units property |
| marginsobject | The page margins |
Input
{
"name": "Client name",
"type": "text",
"default_value": ""
}| Property | Description |
|---|---|
| namestring | The internal name by which the report will refer to this input, for example in defining a filter against it |
| typestring | The data type of the input; determines the type of input field shownOne of: "text", "number", "date" |
| default_valuestring | The default value to use when the user has not entered a value |
| optionSourcearray,string | For "text" type inputs only. An array of string values to show as drop-down options for the input field, or the string ID of a separately-defined data source. When referencing a data source, use the optionSourceField to indicate which field in the data source contains the drop-down values. |
| optionSourceFieldstring | For "text" type inputs only. Use in conjunction with the optionSource property above. Indicates which field in the specified data source contains the string values to use as drop-down selection options for the input field. |
| limitToListboolean | When optionSource is specified and limitToList is true, prevents the user from entering a value not in the list of options for the inputDefault: false |
TextElement
A text label, either static or dynamically calculated
| Property | Description |
|---|---|
| typestring | Must be: "text" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| leftnumber | The distance from the left margin to the left edge of the element, in report units (inches or mm) |
| widthnumber | The width of the element, in report units (inches or mm) |
| heightnumber | The height of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
| textstring | The text to display. Can contain expressions in square brackets, like: The field value is [fieldName] The total is [SUM(fieldName)] Multiplied by 3 is [=fieldName * 3] Percent of total is [=fieldname / SUM('fieldName') * 100] |
| patternstring | A format string used to format a data value or calculation result; uses Excel-style patterns e.g. MM/DD/YY or $#,##0.00. Only applied when the entire text property is a bracket expression resulting in a number or date value |
| fontsizenumber | Font size in points |
| boldboolean | Whether to render the text in boldDefault: false |
| italicboolean | Whether to render the text in italicsDefault: false |
| underlineboolean | Whether to render the text underlinedDefault: false |
| wrapboolean | Whether to wrap text if it extends beyond the width of the elementDefault: true |
BoxElement
A rectangle with border and fill colors and optional corner rounding
| Property | Description |
|---|---|
| typestring | Must be: "box" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| leftnumber | The distance from the left margin to the left edge of the element, in report units (inches or mm) |
| widthnumber | The width of the element, in report units (inches or mm) |
| heightnumber | The height of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
| background_colorstring | The CSS color code for the fill (background) color, e.g. "black" or "#e0da38" |
| border_colorstring | The CSS color code for the stroke (border) color, e.g. "black" or "#e0da38" |
| corner_radiusnumber | The amount of corner rounding |
ChartElement
A chart, showing one or more series of data from the current grouped rows or another data source.
| Property | Description |
|---|---|
| typestring | Which type of chart to drawOne of: "chart-pie", "chart-line", "chart-bar" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| leftnumber | The distance from the left margin to the left edge of the element, in report units (inches or mm) |
| widthnumber | The width of the element, in report units (inches or mm) |
| heightnumber | The height of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
ImageElement
An image
| Property | Description |
|---|---|
| typestring | Must be: "image" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| leftnumber | The distance from the left margin to the left edge of the element, in report units (inches or mm) |
| widthnumber | The width of the element, in report units (inches or mm) |
| heightnumber | The height of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
BarcodeElement
| Property | Description |
|---|---|
| typestring | Must be: "barcode" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| leftnumber | The distance from the left margin to the left edge of the element, in report units (inches or mm) |
| widthnumber | The width of the element, in report units (inches or mm) |
| heightnumber | The height of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
| valuestring | The value to encode in the barcode. Like the textElement text property, can accept calculations or data fields |
BreakElement
A page break. Placed at a vertical position within a report section, this element will trigger a page break in PDF mode at that position each time the section is rendered.
| Property | Description |
|---|---|
| typestring | Must be: "break" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
SubreportElement
Render another report within the current report.
| Property | Description |
|---|---|
| typestring | Must be: "subreport" |
| topnumber | The distance from the top of the section to the top edge of the element, in report units (inches or mm) |
| leftnumber | The distance from the left margin to the left edge of the element, in report units (inches or mm) |
| widthnumber | The width of the element, in report units (inches or mm) |
| heightnumber | The height of the element, in report units (inches or mm) |
| idstring | The element ID for internal use; will be auto-generated if not present |
Section
A horizontal section of the report containing elements, that may be bound to data in the data source and may be repeated one or more times for each underlying data row.
| Property | Description |
|---|---|
| heightnumber | The height of the section, in report units |
| elementsarray | An array of Elements in arbitrary order to display within this report section |
| visibleboolean | Whether the section should be displayed when the report is renderedDefault: true |
BodySection
A section representing the main report body, containing elements and also allowing pivot and sub-level (grouping) configuration.
| Property | Description |
|---|---|
| heightnumber | The height of the section, in report units |
| elementsarray | An array of Elements in arbitrary order to display within this report section |
| visibleboolean | Whether the section should be displayed when the report is renderedDefault: true |
| pivot_enabledboolean | Whether to pivot the main data source, generating columns from unique values in the rowsDefault: false |
| pivot_expressionstring | The expression to evaluate to generate columns. One column will be generated for each unique result of this expression across all rows. |
| pivot_column_sort_bystring | The field name in the underlying data source to sort by when ordering generated columns |
| order_detail_bystring | The field name to sort by when ordering the detail sections |
| pivot_column_leftnumber | The left edge of the pivot column in the report template, measured from the left margin, in report units. The pivot column defines the area in the report template that will be cloned to generate the pivot columns. Any elements defined to lie within the pivot column region will be cloned; other elements will not be cloned. |
| pivot_column_rightnumber | The right edge of the pivot column in the report template, measured from the left margin, in report units. |
| sublevelsarray | An array of Levels, outermost-first, that create a hierarchical (nested) report structure |
Level
A nesting sub-level in the report, used for groupings or drill-down into different data sources.
| Property | Description |
|---|---|
| data_sourcestring | The ID of the data source to use to fill this sub-level, or "__parentgroup" to re-group the rows from a parent grouping |
| headerobject | The Section defining the header to render for each instance of this level |
| footerobject | The Section defining the footer to render for each instance of this level |
| group_bystring | The field name in the data source by which to group this level |
| sort_bystring | The field name by which to sort the groups in this level. If not present, defaults to the group_by field (if any) |
| sort_dirstring | Which direction the groups should be ordered; defaults to "asc" (A->Z)One of: "asc", "desc" |