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
OPTIONAL
versionstring Version of jsreports used to create this report (when created by the designer or report builder API)
OPTIONAL
default_formatstring Not currently usedMust be: "html"
OPTIONAL
titlestring Title of report to be shown to user, for use by plugins listing available reports
OPTIONAL
filtersarray Filters to apply to the report's top-level data source; only matching records will appear in the report
OPTIONAL
inputsarray User-facing inputs to display in the report toolbar, for supplying parameters to the report at runtime
OPTIONAL

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
OPTIONAL
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.
OPTIONAL
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.
OPTIONAL
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
OPTIONAL

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
OPTIONAL
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
OPTIONAL
fontsizenumber Font size in points
OPTIONAL
boldboolean Whether to render the text in boldDefault: false
OPTIONAL
italicboolean Whether to render the text in italicsDefault: false
OPTIONAL
underlineboolean Whether to render the text underlinedDefault: false
OPTIONAL
wrapboolean Whether to wrap text if it extends beyond the width of the elementDefault: true
OPTIONAL

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
OPTIONAL
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
OPTIONAL

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
OPTIONAL

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
OPTIONAL
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
OPTIONAL

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
OPTIONAL

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
OPTIONAL

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
OPTIONAL
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
OPTIONAL

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"