API Schema Reference

The canonical API route is POST /api/v1/render.

The request body is a single DocumentRequest JSON object.

Root: DocumentRequest

Field	Type	Required
settings	Settings	No
pages	Page[]	Yes
header	Section	No
footer	Section	No

Page Sizing

Each page must define its physical size in exactly one of these ways:

• Explicit millimeters: width + height
• Preset size: size

Rules:

• size and width / height are mutually exclusive
• width and height must be provided together
• Preset matching is case-insensitive

Supported preset values:

• a4
• a6
• letter
• legal
• label_100_100
• label_100_150
• label_4_6_in

Section (header / footer)

header and footer share the same shape:

• height: number in mm
• elements: Element[]

Behavior:

• header is repeated on every page
• footer is repeated on every page
• header elements render in absolute page coordinates
• footer elements render with a bottom offset of page.height - footer.height
• footer.height reduces the available body height for pagination
• header does not automatically push body elements down
• optional settings.page_margin / pages[].margin define a body content box
• when page margins are configured, body x/y become relative to the content box
• body elements outside the content box fail validation

Settings

Field	Type
defaults	Defaults
metadata	Metadata
output	OutputSettings
profile	string
page_margin	PageMargin

Defaults uses unified style objects:

• text: TextStyle
• stroke: StrokeStyle
• fill: FillStyle
• shape: ShapeDefaults

OutputSettings

• mode: binary or file (response presentation mode)
• file_name: optional custom file name used in both binary and file modes
• default behavior is binary
• both modes return PDF bytes
• binary uses Content-Disposition: inline; filename="..."
• file uses Content-Disposition: attachment; filename="..."
• missing file_name falls back to gPdf-MMDDHHmmssSSS.pdf

Element Types

elements[] is a tagged union by type:

• text
• barcode
• line
• rect
• circle
• ellipse
• polygon
• link
• image
• table
• stack

Image payloads currently support:

• Raster: jpg / jpeg / png / webp
• Vector image payloads: svg

Barcode format values are case-insensitive, and - / _ are treated as equivalent separators.

Supported barcode formats in the current build:

• 2D / matrix: qrcode (qr), microqr (micro-qr), pdf417, micropdf417 (micro-pdf417), datamatrix (data-matrix), gs1datamatrix (gs1-datamatrix, gs1_datamatrix), aztec, maxicode, gs1qrcode (gs1-qrcode, gs1_qr, gs1-qr)
• 1D / linear: code128 (code-128), code128a (code-128a), code128b (code-128b), code128c (code-128c), gs1128 (gs1-128), code39 (code-39), code93 (code-93), codabar, ean8 (ean-8), ean13 (ean-13), upca (upc-a), upce (upc-e), itf (interleaved2of5), itf14 (itf-14), gtin8 (gtin-8), gtin12 (gtin-12), gtin13 (gtin-13), gtin14 (gtin-14), isbn (isbn-13), sscc (sscc-18)
• Other business formats: msi (msi-plessey), msi10 (msi-10), msi11 (msi-11), msi1010 (msi-1010), msi1110 (msi-1110), upus10 (s10), uspsimb (usps-imb, intelligent-mail), upcacomposite (upca-composite), upcecomposite (upce-composite)

stack

• body-only flow element for table followed by one or more blocks
• children[0] must be table
• later children must be block
• gap is the vertical distance between the table's final bottom and the next block's start

block

• follow-up content group used inside stack
• no own x/y/width/height
• child x keeps current body semantics
• child y is relative to the block start
• cannot nest table / stack / block

x_anchor

• supported by text, barcode, rect, image, and link
• mutually exclusive with x
• supports page_* and content_* references everywhere
• supports table_left / table_right only inside stack -> block
• text requires width when x_anchor is used:
  • plain text / spans shorthand use style.width
  • block text uses frame.width

Unified Vector Styling

Vector elements use the same schema:

• stroke: StrokeStyle
• fill: FillStyle

This is shared by line / rect / circle / ellipse / polygon. Table borders also use the same StrokeStyle model for grid.top/right/bottom/left/horizontal/vertical and cell.borders.

StrokeStyle includes optional compound for compound strokes. The currently supported kind is double.

Hyperlink Model

• Attached links: text / barcode / line / rect / circle / ellipse / polygon / image support optional link: LinkSpec
• Independent hotspots: type: "link" supports area-based click targets without visible graphics
• LinkSpec.target supports:
  • URL: { "type": "url", "url": "https://..." }
  • Page destination: { "type": "page", "page": 2, "x": 10, "y": 20 }
• URL schemes are restricted to http, https, mailto, tel
• Invalid link fields fail validation instead of being silently ignored

Text Typography

• public text accepts three input forms:

  • plain text shorthand
  • rich spans shorthand
  • block text

• all three forms are handled consistently during validation and rendering

• block text is the most complete and recommended form

• text.rotation accepts arbitrary integer degree values

• image.rotation accepts arbitrary degree values

• barcode.rotation and barcode-attached text currently support only 0/90/180/270

• for POST /api/v1/render, only system.page and system.total_pages are publicly guaranteed built-in variables

• if you need business-data substitution, use POST /api/v1/template-render

• computed is not currently exposed as a public capability

• _if is template metadata and is not evaluated by POST /api/v1/render

• font_family omitted or empty:

  • the current style keeps inheriting the parent font intent
  • if no explicit font exists in the chain, the engine uses automatic fallback mode

• font_family present and font_mode omitted:

  • effective mode is strict

• font_mode = "strict":

  • explicit font must cover the current scope

• font_mode = "prefer":

  • explicit font is preferred, but fallback is still allowed

• font_weight supports normal | medium | semibold | bold

• font_style supports normal | italic

• in strict, the requested weight/style must resolve to a real face

• in prefer and automatic mode, the engine prefers the requested weight/style, then may fall back to the nearest usable face

• font_mode cannot appear without a same-level font_family

• Public requests should only use strict and prefer

• letter_spacing is a single numeric multiplier

• omitted letter_spacing means no extra tracking

• 0 means no extra tracking

• values above 0 apply uniform tracking based on a fixed 0.2em step

• examples:

  • 0.2 = 0.04em
  • 1 = 0.2em
  • 1.12 = 0.224em
  • 2 = 0.4em

• automatic tracking is not supported

• background, decoration, and link_style are object fields on TextStyle

• background.padding uses logical directions:

  • inline
  • block
  • optional start/end overrides

• there is no separate background preset enum; Square, Soft, and Capsule are parameter combinations

• recommended defaults:

  • badge uses Square
  • highlight uses Soft
  • Capsule is optional, not the default

• span.style may override typography fields, but not box layout fields such as width, height, or alignment

Table Schema

The only supported public table schema is centered on:

• columns
• rows
• cell
• header
• row_header
• body
• grid
• pagination

Key rules:

• row headers are modeled as columns[].role = "row_header"
• grid.top/right/bottom/left/horizontal/vertical accept StrokeStyle
• columns[].width is always a width object: fixed, percent, or auto
• percent and auto require table.width
• grouped headers live in header.rows; leaf headers still use columns[].header
• complex body cells use content; grouped header cells and columns[].header share the same text contract (string | number | boolean | null | BlockTextContent)
• TableCellStyle supports content_offset_x / content_offset_y
• row objects may only contain keys declared in columns[].key
• legacy lightweight payloads such as data/layout/theme/row_headers/corner/style_overrides are no longer part of the public API

Notes

• Deprecated payloads (LabelRequest[], pdf_params, items, 1d_params, 2d_params) are not part of the current public schema.
• Service defaults are applied automatically when the request omits a field.
• See JSON 数据结构 for complete field-level details.