PageWright JSON Spec Language Reference

This is the PageWright™ JSON Spec Language Reference. PageWright is a PDF page-layout engine: you describe a document as a JSON spec - its pages, text, tables, images, charts, forms and structure - and the engine flows it onto pages and writes a tagged, standards-compliant PDF.

Every page of this manual was produced by the engine itself from a JSON spec (sample/guide-spec-reference.json), so it doubles as a worked example: the cover, the table of contents, the running heads and folios, the code boxes, the reference tables, and the index and glossary at the back are all ordinary engine features described in these pages.

A PageWright document is a single JSON file. It is not a program and there is no scripting: you describe what the document contains - its pages, text, tables, pictures, charts, forms and structure - and the engine decides where everything lands, flows it onto pages, and writes a tagged, standards-compliant PDF.

That distinction matters. You never position a line of text or ask for a page break in the middle of a paragraph. You say "here is a heading, here are four paragraphs, here is a table", and the engine paginates, wraps, justifies, hyphenates, keeps headings with their text, repeats table headers across page breaks, and numbers everything.

The smallest useful document is three lines:

{
  "blocks": [
    {
      "type": "paragraph",
      "text": "Hello."
    }
  ]
}

Render it from the command line:

pagewrightapp hello.json hello.pdf

Every spec is a JSON object. At the top sit document-wide settings - metadata, page setup, default styling - and one of two content keys:

• blocks - a flat list of elements, for a document with one page setup throughout.
• sections - a list of sections, each with its own page setup and its own blocks, for a document that changes orientation, margins, column count or folio style partway through.

A document uses one or the other, never both. Everything else is optional.

{
  "title": "Quarterly Report",
  "author": "Appligent, Inc.",
  "tagged": true,
  "lang": "en-US",
  "pageSetup": {
    "size": "Letter",
    "margins": 64,
    "footer": {
      "center": "{{page}}"
    }
  },
  "defaultStyle": {
    "fontFamily": "Helvetica",
    "fontSize": 11
  },
  "blocks": [
    {
      "type": "heading",
      "level": 1,
      "text": "Summary"
    },
    {
      "type": "paragraph",
      "text": "Revenue rose nine per cent."
    }
  ]
}

Every element gets the same treatment: what it is for, a worked example you can paste into a spec, and a table of its keys. In those tables:

• Key is the JSON property name, spelled exactly as the engine expects it.
• Type is string, number, integer, boolean, object, array of X, or the name of a shared definition documented in Part IV.
• Default is what the engine uses when you leave the key out. An empty cell means the key has no default - leaving it out simply means the feature is off.
• Description says what the key does. Required marks a key the element cannot be built without.

Keys that every block accepts - style, id, lang, position and the rest - are documented once, in their own chapter, and left out of the per-element tables so that what you see there is what is specific to that element.

The keys below may appear on any element. They are listed here once and omitted from the individual element tables.

Elements that put words on the page.

The paragraph element

Type name: paragraph.

The workhorse. A paragraph is a run of prose that the engine wraps, justifies and paginates for you: give it text for a single unstyled string, or runs when parts of it need their own styling, a link, a footnote or a cross-reference. Whitespace is collapsed - every run of spaces, tabs and newlines becomes one space - so you can format the JSON however you like without changing the output. A paragraph splits across pages and columns at line boundaries, with widow and orphan control.

Example

{
  "type": "paragraph",
  "runs": [
    {
      "text": "Tighten the retaining bolt to "
    },
    {
      "text": "18 N·m",
      "style": {
        "weight": "bold"
      }
    },
    {
      "text": " before flight."
    }
  ]
}

Figures aligned on a decimal tab, with a dot leader

{
  "type": "paragraph",
  "style": {
    "tabs": [
      {
        "at": 60,
        "align": "left"
      },
      {
        "at": 300,
        "align": "decimal",
        "leader": "dot"
      }
    ]
  },
  "text": "Retaining bolt\t18.00"
}

Keys

The heading element

Type name: heading.

A titled break in the flow, at level 1 to 6. Headings do more than look large: each one is collected into the table of contents, becomes a PDF bookmark, and is tagged H1-H6 for accessibility. Give a heading an id and other blocks can cross-reference it. With document numbering enabled the engine writes the number for you, so "1.2 Assembly" is something you never type.

Example

{
  "type": "heading",
  "level": 2,
  "id": "assembly",
  "text": "Assembly"
}

An appendix heading, lettered by document numbering

{
  "type": "heading",
  "level": 1,
  "appendix": true,
  "id": "app-data",
  "text": "Data tables"
}

Keys

The list element

Type name: list.

A bulleted or numbered list. Each item is itself a list of blocks, so an item can hold several paragraphs, a nested list, an image or a table - not just one line of text. Set ordered for numbers, and nest lists to whatever depth the material needs.

Example

{
  "type": "list",
  "ordered": true,
  "items": [
    {
      "blocks": [
        {
          "type": "paragraph",
          "text": "Seat the motor."
        }
      ]
    },
    {
      "blocks": [
        {
          "type": "paragraph",
          "text": "Attach the shock cord."
        }
      ]
    }
  ]
}

A multi-level numbered outline (1, 1.1, 1.1.1)

{
  "type": "list",
  "ordered": true,
  "multiLevel": true,
  "items": [
    {
      "blocks": [
        {
          "type": "paragraph",
          "text": "Preparation"
        }
      ],
      "items": [
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "Inspect the airframe."
            }
          ]
        },
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "Check the motor mount."
            }
          ]
        }
      ]
    },
    {
      "blocks": [
        {
          "type": "paragraph",
          "text": "Assembly"
        }
      ]
    }
  ]
}

Keys

The pre element

Type name: pre. Accepted aliases: code.

Verbatim text, drawn line for line in a monospace face with every space preserved: a console session, a configuration file, a code listing. Unlike a paragraph it never reflows. fit shrinks an over-wide line to the column; wrap breaks it onto an indented continuation instead. Supplying tokens instead of text gives syntax coloring, and a caption promotes the block to a numbered listing.

Example

{
  "type": "code",
  "language": "python",
  "lineNumbers": true,
  "caption": "Reading a spec file.",
  "text": "def load(path):\n    return json.load(open(path))"
}

Syntax-colored tokens, with one line highlighted

{
  "type": "code",
  "language": "python",
  "lineNumbers": true,
  "highlightLines": [
    1
  ],
  "tokens": [
    [
      {
        "text": "def ",
        "color": "#CF222E"
      },
      {
        "text": "load",
        "color": "#8250DF"
      },
      {
        "text": "(path):",
        "color": "#1F2328"
      }
    ],
    [
      {
        "text": "    return ",
        "color": "#CF222E"
      },
      {
        "text": "json",
        "color": "#0550AE"
      },
      {
        "text": ".load(open(path))",
        "color": "#1F2328"
      }
    ]
  ]
}

Keys

Elements that group other elements or shape the page.

The container element

Type name: container.

A group of blocks treated as one. A container is how you give several blocks a shared background, border, padding or margin - a boxed sidebar, a tinted panel, a card. It is also the unit of keepTogether, which asks the engine not to split the group across a page break.

Example

{
  "type": "container",
  "keepTogether": true,
  "style": {
    "background": "#eef2f8",
    "padding": 10,
    "border": {
      "width": 0.75,
      "color": "#2a4d7a"
    }
  },
  "blocks": [
    {
      "type": "paragraph",
      "text": "A boxed aside."
    }
  ]
}

Keys

The columns element

Type name: columns.

A row of side-by-side columns, each holding its own block. Use it for a two-up comparison, a label-and-value pair, or a picture beside its explanation. This is different from pageSetup.columns, which pours a single stream of text down multiple newspaper columns; columns places distinct content side by side.

Example

{
  "type": "columns",
  "gap": 18,
  "columns": [
    {
      "width": "50%",
      "block": {
        "type": "paragraph",
        "text": "Left."
      }
    },
    {
      "width": "50%",
      "block": {
        "type": "paragraph",
        "text": "Right."
      }
    }
  ]
}

Keys

The cardGrid element

Type name: cardGrid. Accepted aliases: cardgrid.

A grid of cards that wraps: you supply the items, the engine decides how many fit per row and flows the rest onto the next. The signature layout of a dashboard or a product summary page.

Example

{
  "type": "cardGrid",
  "minColWidth": 150,
  "gap": 12,
  "items": [
    {
      "type": "container",
      "blocks": [
        {
          "type": "paragraph",
          "text": "One"
        }
      ]
    },
    {
      "type": "container",
      "blocks": [
        {
          "type": "paragraph",
          "text": "Two"
        }
      ]
    }
  ]
}

Keys

The spacer element

Type name: spacer.

Blank vertical space, in points. The simplest way to open a gap.

Example

{
  "type": "spacer",
  "height": 12
}

Keys

The rule element

Type name: rule.

A horizontal line, with a thickness, color and inset from the column edges.

Example

{
  "type": "rule",
  "thickness": 0.5,
  "color": "#cccccc",
  "inset": 0
}

Keys

The pagebreak element

Type name: pagebreak. Accepted aliases: page-break.

Forces the following content onto a fresh page. Skipped when the cursor is already at the top of a page, so it never leaves a blank sheet behind.

Example

{
  "type": "pagebreak"
}

Keys

The tabular grid, its rows, cells and headers.

The table element

Type name: table.

A tabular grid with sized columns, header rows that repeat across page breaks, spanning cells, per-cell styling and full tagged-PDF structure. Cells hold blocks, so a cell can contain paragraphs, images, lists or a nested table. A long table splits across pages - and, when a single row is taller than a page, within a row.

Example

{
  "type": "table",
  "caption": "Quarterly totals.",
  "headerRows": 1,
  "headerRepeat": true,
  "columns": [
    {
      "width": "60%"
    },
    {
      "width": "40%",
      "align": "right"
    }
  ],
  "rows": [
    {
      "header": true,
      "cells": [
        "Quarter",
        "Units"
      ]
    },
    {
      "cells": [
        "Q1",
        "1,240"
      ]
    }
  ]
}

A spanning header row and one boxed total cell

{
  "type": "table",
  "headerRows": 1,
  "border": {
    "width": 0.5,
    "color": "#999999"
  },
  "columns": [
    {
      "width": "50%"
    },
    {
      "width": "25%",
      "align": "right"
    },
    {
      "width": "25%",
      "align": "right"
    }
  ],
  "rows": [
    {
      "header": true,
      "cells": [
        {
          "colspan": 3,
          "style": {
            "background": "#e8edf4"
          },
          "blocks": [
            {
              "type": "paragraph",
              "text": "Regional results"
            }
          ]
        }
      ]
    },
    {
      "cells": [
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "North"
            }
          ]
        },
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "112"
            }
          ]
        },
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "100"
            }
          ]
        }
      ]
    },
    {
      "cells": [
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "Total"
            }
          ]
        },
        {
          "style": {
            "border": {
              "width": 2,
              "color": "#1f4e79"
            }
          },
          "blocks": [
            {
              "type": "paragraph",
              "text": "314"
            }
          ]
        },
        {
          "blocks": [
            {
              "type": "paragraph",
              "text": "310"
            }
          ]
        }
      ]
    }
  ]
}

Keys

Raster images, vector art, and generated graphics.

The image element

Type name: image.

A raster picture - PNG, JPEG, GIF, TIFF or WebP, or HEIC/HEIF on macOS. Size it with width and height, cap it with maxHeight, or let it take its natural size; the file's own orientation and ICC profile are honored. Floating an image with float lets text wrap beside it. A caption is drawn beneath and collected into the list of figures; alt supplies the text an assistive reader announces, and is required for a document that must pass PDF/UA.

Example

{
  "type": "image",
  "src": "diagram.png",
  "width": "45%",
  "float": "right",
  "caption": "The airflow around the fin root.",
  "alt": "A fin with airflow lines curving around its root fillet."
}

A left-floated, captioned figure with alt text

{
  "type": "image",
  "src": "fin.png",
  "width": "40%",
  "float": "left",
  "caption": "The fin planform.",
  "alt": "A trapezoidal fin, its root chord longer than its tip."
}

A landscape scan turned upright (rotate 90) into a portrait box

{
  "type": "image",
  "src": "scan.png",
  "width": 120,
  "rotate": 90,
  "caption": "The fold-out, turned upright.",
  "alt": "A wide schematic rotated a quarter-turn clockwise to read upright."
}

Keys

The shape element

Type name: shape.

Vector geometry drawn directly: a rectangle, line, ellipse, polygon or an arbitrary bezier path. Fills accept flat color or a gradient, and strokes accept width, color and dash. Use shapes for rules, callout pointers, diagram primitives and decorative panels.

Example

{
  "type": "shape",
  "shape": "rect",
  "width": 200,
  "height": 40,
  "fill": {
    "type": "linear",
    "angle": 0,
    "stops": [
      {
        "offset": 0,
        "color": "#1f4e79"
      },
      {
        "offset": 1,
        "color": "#7ba44f"
      }
    ]
  }
}

Keys

The svg element

Type name: svg.

An imported SVG drawing, rendered as real PDF vector art rather than a picture of one - so it stays sharp at any zoom and prints at full device resolution. A broad practical slice is supported: groups and nested transforms, every basic shape and the full path grammar, solid/gradient paint with per-stop opacity, a CSS <style> sheet, a <defs> library reused through <use>/<symbol>, multi-line <text>/<tspan>, and compositing - clip-path, <mask> (even-odd knockout), <pattern> tiling, a filter drop shadow, and the root viewport clip. Raster filters (a blur of content, color matrices) have no vector form and are skipped.

Example

{
  "type": "svg",
  "src": "logo.svg",
  "width": 120
}

Keys

The chart element

Type name: chart.

A data chart drawn by the engine: bar, line, area, pie, scatter, radar, heatmap, gauge, box plot, candlestick, treemap, sankey and more, including combination charts with a secondary axis. You supply the series; the engine chooses tick intervals, draws the axes, grid, legend and labels. Give it an alt so the picture has a spoken description.

Example

{
  "type": "chart",
  "chartType": "bar",
  "title": "Units by quarter",
  "size": {
    "width": "100%",
    "height": 180
  },
  "yAxis": {
    "label": "Units",
    "grid": true
  },
  "series": [
    {
      "name": "2026",
      "points": [
        [
          0,
          12
        ],
        [
          1,
          19
        ],
        [
          2,
          15
        ]
      ]
    }
  ],
  "alt": "A bar chart of units for three quarters: 12, 19 and 15."
}

Reference lines and a shaded value band

{
  "type": "chart",
  "chartType": "line",
  "title": "API latency (p95)",
  "size": {
    "height": 220
  },
  "xAxis": {
    "label": "Hour",
    "min": 0,
    "max": 24,
    "majorTick": 6
  },
  "yAxis": {
    "label": "ms",
    "min": 0,
    "max": 300,
    "majorTick": 50,
    "grid": true
  },
  "bands": [
    {
      "yFrom": 0,
      "yTo": 100,
      "color": "#2e8b57",
      "label": "Healthy"
    }
  ],
  "referenceLines": [
    {
      "y": 200,
      "label": "SLA",
      "color": "#c0202a"
    },
    {
      "y": 120,
      "label": "Target",
      "color": "#2e6f2e",
      "dashed": true
    }
  ],
  "series": [
    {
      "name": "p95",
      "points": [
        [
          0,
          60
        ],
        [
          6,
          88
        ],
        [
          12,
          175
        ],
        [
          18,
          205
        ],
        [
          24,
          95
        ]
      ]
    }
  ],
  "alt": "A latency line that crosses a 200 ms SLA reference line."
}

A horizontal bar with a value threshold on the X axis

{
  "type": "chart",
  "chartType": "bar",
  "horizontal": true,
  "title": "Revenue vs target",
  "size": {
    "height": 180
  },
  "categories": [
    "North",
    "South",
    "East",
    "West"
  ],
  "yAxis": {
    "unit": "K",
    "min": 0,
    "max": 120,
    "majorTick": 20
  },
  "referenceLines": [
    {
      "x": 80,
      "label": "Target",
      "color": "#c0202a"
    }
  ],
  "series": [
    {
      "name": "Revenue",
      "points": [
        [
          0,
          55
        ],
        [
          1,
          72
        ],
        [
          2,
          95
        ],
        [
          3,
          110
        ]
      ]
    }
  ],
  "alt": "Four regional revenue bars against an 80K target line."
}

Error bars — a symmetric mean +/- SD whisker on every point

{
  "type": "chart",
  "chartType": "line",
  "title": "Reaction time",
  "size": {
    "height": 200
  },
  "markers": true,
  "xAxis": {
    "label": "Session",
    "min": 1,
    "max": 4,
    "majorTick": 1
  },
  "yAxis": {
    "label": "ms",
    "min": 0,
    "max": 500,
    "majorTick": 100,
    "grid": true
  },
  "series": [
    {
      "name": "RT",
      "error": 35,
      "points": [
        [
          1,
          420
        ],
        [
          2,
          395
        ],
        [
          3,
          360
        ],
        [
          4,
          350
        ]
      ]
    }
  ],
  "alt": "A reaction-time line with a plus-or-minus 35 ms error bar on every point."
}

Keys

The barcode element

Type name: barcode.

A barcode or 2-D symbol - QR, Data Matrix, PDF417, Code 128, EAN, UPC and the rest of the zint symbology set. Supply the payload as data; the engine encodes and draws it at a size that scans.

Example

{
  "type": "barcode",
  "code": "qrcode",
  "data": "https://appligent.com",
  "width": 90,
  "alt": "QR code linking to appligent.com"
}

Keys

The math element

Type name: math. Accepted aliases: equation.

A display equation. Supply the visual as pre-rendered SVG and the meaning as Presentation MathML: the engine draws the SVG and embeds the MathML as an associated file on the Formula structure element, so assistive technology reads the real mathematics rather than a picture. With equation numbering enabled the engine adds the number in the right gutter.

Example

{
  "type": "math",
  "align": "center",
  "mathml": "<math><mi>E</mi><mo>=</mo><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup></math>",
  "src": "energy.svg",
  "alt": "E equals m c squared"
}

Keys

The mermaid element

Type name: mermaid. Accepted aliases: diagram.

A diagram written as code. Supply the rendered SVG and the engine places it as vector art; without one it degrades to a captioned panel showing the diagram source, so the information is never lost.

Example

{
  "type": "mermaid",
  "src": "flow.svg",
  "source": "graph TD; A-->B;",
  "alt": "A two-node build pipeline."
}

Keys

Importing pages from PDF files you already have.

The pdf element

Type name: pdf.

One or more pages lifted from an existing PDF and placed into the flow as real vector content - not a screenshot. Use it to fold a supplied datasheet, certificate or signed page into a generated document.

Example

{
  "type": "pdf",
  "src": "datasheet.pdf",
  "page": 1,
  "width": "100%",
  "caption": "Supplied datasheet, page 1."
}

Keys

The pdf-contact-sheet element

Type name: pdf-contact-sheet. Accepted aliases: contact-sheet.

A grid of thumbnails of every page in a PDF, with optional page numbers. A quick visual index of a large document.

Example

{
  "type": "pdf-contact-sheet",
  "src": "report.pdf",
  "columns": 4,
  "labels": true
}

Keys

Generated front and back matter.

The toc element

Type name: toc. Accepted aliases: lof, lot, lol, loc.

An automatic table of contents built from the document's headings, with dot leaders and exact page numbers, every row an internal link. The page numbers are exact because the engine iterates: the contents list changes the pagination, so it re-counts until the numbers stop moving.

Example

{
  "type": "toc",
  "title": "Contents",
  "maxLevel": 2
}

Keys

The toc element

Type name: toc. Accepted aliases: lof, lot, lol, loc.

An automatic list of figures, tables or listings - lof, lot and lol are the same element filtered to a different kind of caption. Each row is a linked "caption ...... page" line, built the same converging way as the table of contents.

Example

{
  "type": "lof",
  "title": "List of Figures"
}

A list of tables (the lot alias)

{
  "type": "lot",
  "title": "List of Tables"
}

Keys

The index element

Type name: index.

A back-of-book index. You supply the terms; the engine scans the drawn text as it lays the document out, records every page a term actually appears on, collapses runs of consecutive pages into ranges, and renders the result in columns with letter headings - every page number a working link. Chinese indexes sort the way their readers expect: collation chooses pinyin (Simplified) or stroke-count-then-radical (Traditional) order from an embedded Unihan-derived table, and a per-entry sortAs overrides the reading where dictionaries disagree.

Example

{
  "type": "index",
  "columns": 2,
  "letterHeadings": true,
  "collapseRanges": true,
  "terms": [
    "stability",
    "recovery",
    "motor"
  ]
}

Keys

The glossary element

Type name: glossary.

A list of defined terms. With autoLink on, the first appearance of each term in the body becomes a link to its definition.

Example

{
  "type": "glossary",
  "autoLink": true,
  "entries": [
    {
      "term": "apogee",
      "definition": "The highest point of the flight."
    }
  ]
}

Keys

The bibliography element

Type name: bibliography. Accepted aliases: references.

A reference list built from structured entries (author, title, container, publisher, year, DOI...) or a pre-formatted text, cited from body runs with cite. The numeric style numbers entries in order of first citation (Vancouver) and renders markers as [1] or [1, 3]; the author-year style renders (Knuth 1984) and sorts the list alphabetically. Every citation links to its entry, and with backlink on each entry links back to its first citation. references is an accepted alias.

Keys

The endnotes element

Type name: endnotes.

Collects every note run in the document and renders them as a numbered end-matter list, each marker linking to its note and each note linking back - the alternative to page-bottom footnotes for journals and books that gather notes at the end.

Keys

Set-off editorial material.

The callout element

Type name: callout. Accepted aliases: admonition, note.

A set-off note, tip or warning in a tinted, bordered box. Tagged as an Aside, so assistive technology announces it as an aside rather than as body text.

Example

{
  "type": "callout",
  "variant": "warning",
  "title": "Caution",
  "blocks": [
    {
      "type": "paragraph",
      "text": "Never approach a rocket that failed to launch."
    }
  ]
}

A tip

{
  "type": "callout",
  "variant": "tip",
  "blocks": [
    {
      "type": "paragraph",
      "text": "Render with -map to get the layout geometry back as JSON."
    }
  ]
}

Keys

Interactive AcroForm fields.

The field element

Type name: field.

An interactive AcroForm field: text box, checkbox, radio group, dropdown, list box, button or signature. The field is a real form widget in the output PDF - fillable in any viewer - with a label, tooltip, default value and tab order.

Example

{
  "type": "field",
  "field": "text",
  "name": "customer",
  "label": "Customer name",
  "width": "60%",
  "tooltip": "Full legal name"
}

A radio-button group

{
  "type": "field",
  "field": "radio",
  "name": "size",
  "label": "Size",
  "options": [
    "Small",
    "Medium",
    "Large"
  ],
  "value": "Medium"
}

A signature field

{
  "type": "field",
  "field": "signature",
  "name": "approval",
  "label": "Approved by",
  "width": "60%"
}

Keys

Elements that build content from a data context.

The repeat element

Type name: repeat.

Builds content from data: names an array in the data context and clones its template blocks once per element, binding {{...}} placeholders as it goes. One template, N rendered sections.

Example

{
  "type": "repeat",
  "for": "lineItems",
  "as": "item",
  "blocks": [
    {
      "type": "paragraph",
      "text": "{{item.sku}}  -  {{item.qty}}"
    }
  ]
}

Keys