Document schema

The full JSON grammar for the `template` field — every node, every property, every helper.

Document schema

This page is the canonical reference for what you can put inside template. For tutorials and worked examples, jump to Templates.

Top level

{
  "template": {
    "page":     { ... },
    "header":   [ ... ],
    "footer":   [ ... ],
    "body":     [ ... ]
  }
}
Field Type Required Notes
page object yes Page setup.
header array no Drawn on every page above the body.
footer array no Drawn on every page below the body.
body array yes The main content.

page

{
  "page": {
    "size":        "A4",
    "margin":      "20mm",
    "orientation": "portrait",
    "background":  [ ... ],
    "firstPage":   { /* same shape as `page` — overrides for first page */ }
  }
}
Field Type Notes
size "A4" | "A5" | "A3" | "Letter" | "Legal" | [w, h] [w, h] in pt.
margin string | object "20mm" for all sides, or { "top": ..., "right": ..., "bottom": ..., "left": ... }.
orientation "portrait" | "landscape" Default "portrait".
background array Absolutely positioned nodes drawn behind the body, repeated on every page.
firstPage object Overrides for the first page only — same fields as page.

Body nodes

The body is an array of nodes. Each node has exactly one type key (text, spacer, row, table, image, qr, barcode, page-break).

text

{ "text": "Hello",
  "style": { ... },
  "color": "#000",
  "align": "left" }
Field Type Notes
text string The string to render. Go-template tags allowed.
style object See Style.
align left | center | right | justify Shortcut for style.align.
color hex Shortcut for style.color.

spacer

{ "spacer": "8mm" }

A single string, vertical space.

row and col

{ "row": [
  { "col": { "span": 6, "body": [...] }},
  { "col": { "span": 6, "body": [...] }}
]}
Field Type Notes
span int 1–12 Sum across siblings ≤ 12.
body array Nested body nodes.
align string left/center/right.
padding string | object "4mm" or { "top": ..., ... }.
gap string Horizontal gap between this col and the next.

table

{
  "table": {
    "columns": [
      { "span": 7, "align": "left" },
      { "span": 5, "align": "right" }
    ],
    "header": [ [ ... ] ],
    "rows":   [ [ ... ], [ ... ] ],
    "footer": [ [ ... ] ],
    "style": {
      "rowHeight":    "11mm",
      "headerFill":   "#f3f4f6",
      "borderColor":  "#e5e7eb",
      "borderWidth":  0.5,
      "headerRepeat": true,
      "stripes":      "#fafafa"
    }
  }
}

A row is an array of cells. A cell is either a node (treated as body: [node]), or:

{ "text": "...", "style": { ... }, "colspan": 2, "rowspan": 1, "align": "right" }

colspan and rowspan follow standard HTML-table semantics.

image

See Images, QR & barcode for the full reference.

{ "image": "https://...", "width": "30mm" }

qr

{ "qr": "https://gpdf.dev", "size": "20mm" }

barcode

{ "barcode": { "value": "012345678905", "format": "ean13" }, "width": "60mm" }

page-break

{ "page-break": true }

Or with options:

{ "page-break": { "if": "{{gt .pages 1}}" }}

style

Every place that accepts a style takes the same object:

Field Type Notes
font string Family name. Default Inter for Latin, auto-fallback for CJK.
fontSize number Points. Default 11.
weight regular | bold Default regular.
style regular | italic Default regular.
color hex Default #000.
align left | center | right | justify Default left.
lineHeight number Multiplier of fontSize. Default 1.4.
letterSpacing number Extra pt between glyphs. Default 0.
hyphenate boolean Latin only. Default false.

Units

Anywhere a length is expected, you can pass any of:

Unit Example Conversion
Points (pt) "12pt" base unit; 1 pt = 1/72 in
Millimetres (mm) "20mm" 1 mm ≈ 2.835 pt
Centimetres (cm) "2cm" 1 cm = 28.35 pt
Inches (in) "1in" 1 in = 72 pt

Numbers without a unit are treated as points.

Helpers (Go-template functions)

In addition to the standard Go-template functions (if, range, with, len, …), gpdf-api adds a small set of helpers you can use inside {{ ... }} tags:

Helper Example Notes
printf {{.total | printf "%.2f"}} Standard Go fmt.
add / sub / mul / div {{add .page 1}} Numeric arithmetic.
eq / ne / gt / lt {{if gt .page 1}}…{{end}} Comparisons.
upper / lower / title {{upper .name}} String case.
trunc {{trunc 30 .description}} Truncate to N chars.
formatTime {{formatTime "2006-01-02" .createdAt}} Go-style time format.
tableRows {{ tableRows .items "name,qty,amount" }} Builds an array of cells from data.

tableRows is the only non-standard helper that's worth a closer look:

{ "table": {
  "columns": [{ "span": 8 }, { "span": 4, "align": "right" }],
  "rows": "{{ tableRows .items \"name,amount\" }}"
}}

With data.items = [{name:"A", amount:100}, {name:"B", amount:200}], this renders a 2-row table without you having to escape JSON inside JSON.

Implicit template variables

Inside the header, footer, and body, two extra variables are always present:

Variable Notes
.page 1-indexed current page.
.pages Total page count.

options

The options block on the request — not part of template, but lives next to it. See POST /v1/pdf.

Field Notes
filename Content-Disposition filename.

Things that aren't supported

  • position: absolute outside of page.background and watermarks.
  • Floats (CSS float: right) — use row/col with explicit spans.
  • Variable fonts other than the default named instance.
  • Annotations / hyperlinks pointing inside the document (anchors are v2).
  • Outline / bookmarks (v2).
  • Vertical Japanese (縦書き).

If you hit a limitation that blocks you, please open an issue.

Something unclear or missing on this page?