# Report and PDF reference

### `<report>`

The root element: a report's parameters, data sources, preparation and output files. Save and publish a version before running or scheduling it.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `schemaVersion` | integer | `1` | Version of the report format. Only `1` is supported. |
| `snapshotRetentionDays` | integer | `30` | Days to keep the data captured for each run, so a failed run can be retried or rendered again; 1 to 3650. |

Children: `parameters`, `sources`, `preparation`, `transforms`, `outputs`, `table-plan`, `definition`. Body: none.

### `<parameters>`

The values a person or schedule supplies when the report runs.

Children: `parameter`. Body: none.

### `<parameter>`

One input the report asks for when it runs, such as a date range or a customer.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `name` | string | — | Name used in queries and templates: a letter followed by letters, digits or underscores. |
| `label` | string | — | Label shown to the person running the report. |
| `type` | `STRING`, `INTEGER`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME`, `ENTITY` | — | Kind of value. `ENTITY` expects the TypeID of a record. |
| `required` | boolean | — | Set to `true` if the report cannot run without this value. |
| `entityPrefix` | string | — | For `ENTITY` parameters: the TypeID prefix the value must have. |

Children: `default`, `options`. Body: none.

### `<default>`

The parameter's default, written as JSON: `"0012"` is text and `12` a number. `null` is different from leaving it out.

Children: none. Body: json.

### `<options>`

Fixed choices for a `STRING` parameter: 1 to 100 unique values.

Children: `option`. Body: none.

### `<option>`

One allowed value.

Children: none. Body: text.

### `<sources>`

The queries that load the report's data.

Children: `source`. Body: none.

### `<source>`

One query whose rows become a dataset named after the source. Write MicroSQL or a read-only GraphQL query; parameter values are supplied when the report runs.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `name` | string | — | Name of the dataset this source produces, used by transforms, outputs and templates. `parameters`, `datasets` and `reportMeta` are reserved. |
| `kind` | `MICRO_SQL`, `GRAPHQL` | — | The query language. |
| `resultPath` | string | — | GraphQL only: dot path under `data` to the rows. Leave it out to use the whole result. |
| `cursorVariable` | string | — | GraphQL only: the variable that receives the next page's cursor, so every page is loaded. Needs a `resultPath` pointing at a connection with `edges` and `pageInfo`. |

Children: none. Body: query.

### `<preparation>`

Optional Lua script that adds or reshapes datasets before the outputs are generated. It receives the report's data as `input` and must return it. It has the language and its libraries, including decimal arithmetic, but no `ctx`: fetch data with `<source>` queries.

Children: none. Body: lua.

### `<transforms>`

Scripts that process rows one at a time, in the order listed.

Children: `transform`. Body: none.

### `<transform>`

Lua script that changes or filters each row: it receives the row as `input` and returns the changed row, or `nil` to drop it. It cannot query data.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `dataset` | string | — | The dataset whose rows it processes. |

Children: none. Body: lua.

### `<outputs>`

The files each run produces.

Children: `output`. Body: none.

### `<output>`

One file produced by each run: a PDF, a CSV file or an Excel workbook.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `name` | string | — | File name, such as `customers.csv`. |
| `format` | `PDF`, `CSV`, `XLSX` | — | File type: PDF, CSV or an Excel workbook (`XLSX`). |
| `storage` | `DATABASE`, `FILE` | — | `DATABASE` keeps the file with the run (up to 8 MiB); `FILE` puts it in managed file storage (up to 32 MiB). |
| `folderId` | string | — | With `FILE` storage: the folder to store the file in (a TypeID starting `fld_`). |
| `dataset` | string | — | CSV or single-sheet workbook: the dataset to export. |

Children: `columns`, `sheets`, `template`, `layout`. Body: none.

### `<columns>`

The columns to export, in order.

Children: `column`. Body: none.

### `<column>`

One literal column name, in output order.

Children: none. Body: text.

### `<sheets>`

Workbook only: up to 16 sheets, each with its own dataset and columns. Use this or `dataset`, not both.

Children: `sheet`. Body: none.

### `<sheet>`

One worksheet.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `name` | string | — | Sheet name; unique within the workbook. |
| `dataset` | string | — | The dataset shown on this sheet. |

Children: `columns`. Body: none.

### `<template>`

An embedded PDF document. Write a pdf element here; SwiftXMLPDF provides validation and authoring help.

Children: `pdf`. Body: xml.

### `<layout>`

Visual document layout in JSON. Use either layout or template for an output.

Children: none. Body: json.

### `<table-plan>`

Table selections, filters and ordering in JSON. Sources and parameters must match these selections.

Children: none. Body: json.

### `<definition>`

Complete report definition in JSON. Must be the only child and cannot be combined with report attributes.

Children: none. Body: json.

### `<pdf>`

PDF document. Dimensions are points (72 per inch); default A4 portrait, 40-point margins.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `size` | `A4`, `Letter` | `A4` | Page size. |
| `orientation` | `portrait`, `landscape` | `portrait` | Page orientation. |
| `margin` | number | `40` | Page margin on every side, in points. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: `view`, `table`, `text`, `spacer`, `image`, `barcode`, `qrcode`. Body: none.

### `<view>`

Vertical or horizontal container. Groups child content in the selected layout direction.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: `view`, `table`, `text`, `spacer`, `image`, `barcode`, `qrcode`. Body: none.

### `<table>`

Table of rows and cells.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: `row`. Body: none.

### `<row>`

One table row.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: `cell`. Body: none.

### `<cell>`

One cell in a row; it can hold any content element.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `colspan` | integer | — | Columns the cell spans. It does not merge cells, so set explicit cell widths as well. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: `view`, `table`, `text`, `spacer`, `image`, `barcode`, `qrcode`. Body: none.

### `<text>`

Consecutive whitespace becomes a single space. Default Helvetica 12, leading 2; t:text replaces the body.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `t:text` | expression | — | Expression whose result replaces the element's text. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: none. Body: text.

### `<spacer>`

Empty spacing block; size defaults to 8 points.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: none. Body: none.

### `<image>`

PNG/JPEG source resolved by the CoCoCo app.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `src` | string | — | The image, as a PNG or JPEG `data:` URI. |
| `t:src` | expression | — | Expression that gives the image `data:` URI. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: none. Body: none.

### `<barcode>`

Barcode. Invalid values prevent the PDF from being generated.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `value` | string | — | The value to encode. |
| `t:value` | expression | — | Expression that gives the value to encode. |
| `type` | `code128`, `code39`, `ean13`, `upca` | — | Barcode type. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: none. Body: none.

### `<qrcode>`

QR code; default 96 points.

| Attribute | Type / values | Default | Meaning |
|---|---|---|---|
| `width` | dimension | — | Points or percentage of available width. |
| `height` | dimension | — | Height in points; percentage heights use the content height. |
| `margin-top` | number | — | Space above the element, in points. |
| `margin-left` | number | — | Space to the left of the element, in points. |
| `padding` | number | — | Space between the border and the content, in points. |
| `backgroundColor` | color | — | Background colour. |
| `font` | string | — | Font name available in your installation. |
| `size` | number | — | Font size in points. |
| `color` | color | — | Text colour. |
| `align` | `left`, `center`, `right` | — | Text alignment. |
| `leading` | number | — | Extra space between lines of text, in points. |
| `layout` | `vertical`, `horizontal` | — | How children are arranged: `vertical` stacks them, `horizontal` places them side by side. |
| `borderWidth` | number | — | Border thickness in points. |
| `borderColor` | color | — | Border colour. |
| `value` | string | — | The value to encode. |
| `t:value` | expression | — | Expression that gives the value to encode. |
| `t:if` | expression | — | Condition; this element is omitted when false. |
| `t:elseif` | expression | — | Condition checked when the preceding `t:if` or `t:elseif` was false. |
| `t:else` | string | — | Fallback branch; use an empty value. |
| `t:for` | expression | — | Repeat this element for each item in a list. |
| `t:as` | string | — | Name for the current `t:for` item, or for the `t:let` value. |
| `t:let` | expression | — | Expression whose value is available, under the `t:as` name, inside this element. |
| `t:attr-<name>` | expression | — | Sets any attribute above without a `t:` prefix from an expression, for example `t:attr-width`. |

Children: none. Body: none.