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: absoluteoutside ofpage.backgroundand watermarks.- Floats (CSS
float: right) — userow/colwith 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.
Related
- Templates → — tutorial.
- Style and units → — detail on length and colour parsing.
- POST /v1/pdf → — endpoint reference.
Something unclear or missing on this page?