JSON model fields and enums

Start with the JSON authoring guide for complete input and rendering examples. This page is generated from the public record components, their Javadocs, enum declarations and Jackson subtype annotations reachable from LetterDocument. It does not include implementation classes or unrelated fluent-only helper values.

Reading the types

A record type is a JSON object, List<T> is an array, and Map<String,T> is an object keyed by name. Map<StyleRole,Style> uses the exact role enum names as keys. String is text, Boolean/boolean is true/false, and numeric types require actual JSON numbers. byte[] is a Base64 string. Enum values are case-sensitive strings.

Use schemaVersion: 1. Schema and Maven versions are distinct. Unknown fields, duplicate keys, trailing tokens, numeric enum ordinals, null primitive values and incompatible scalar coercions are rejected. Null boxed/style values mean inheritance/defaults only where their owning contract permits them; required values are still validated during generation.

Some fields such as semanticStyle, defaultAppearance, defaultStyle and baseStyle preserve lower-priority authoring layers. Ordinary callers usually omit them and set style/appearance/theme values directly. No constructor/JSON parse result is a guarantee that the document is renderable.

Object and discriminator reference

BorderBordersBoundsBoxAppearanceBoxBlockCanvasBlockCellAppearanceColumnColumnsBlockComponentBlockDocumentMetadataDocumentSettingsFixedElementGroupBlockHeadingImageBlockImageWatermarkLetterComponentLetterDocumentLetterPartBlockLetterThemeListBlockListItemLocaleSettingsMarginsPaddingPageBreakBlockPageDimensionsPageSpecParagraphPdfAttachmentPositionedContentSectionSignatureStationeryStyleTableAppearanceTableBlockTableCellTableOptionsTableRowGroupTableRowPolicyTextRunTextWatermark

Block discriminator

Select a variant with the type property.

Value	Object fields
canvas	CanvasBlock
columns	ColumnsBlock
box	BoxBlock
letterPart	LetterPartBlock
component	ComponentBlock
group	GroupBlock
heading	Heading
paragraph	Paragraph
list	ListBlock
image	ImageBlock
table	TableBlock
pageBreak	PageBreakBlock

Watermark discriminator

Select a variant with the kind property.

Value	Object fields
text	TextWatermark
image	ImageWatermark

Border

Uniform border on all four cell edges. Values are checked at generation time.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
widthPt	double	nonnegative line width in points
style	BorderStyle	required finite line style
color	String	required six-digit RGB color, including for an invisible border

Borders

Independent optional physical borders for a flowing box.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
top	Border	nullable top border; null means no border
right	Border	nullable right border; null means no border
bottom	Border	nullable bottom border; null means no border
left	Border	nullable left border; null means no border

Bounds

Rectangle measured from a containing zone's upper-left corner, in millimeters. The x axis runs right and the y axis runs down. For a fixed element the containing zone is TOP or BOTTOM; a BOTTOM_LAST signature uses the last-page signature zone. Construction performs no validation. Generation requires finite, nonnegative x/y, positive width/height, and a rectangle fitting inside its containing zone.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
x	double	horizontal offset from the zone's left edge, in millimeters
y	double	vertical offset from the zone's top edge, in millimeters
width	double	rectangle width in millimeters
height	double	rectangle height in millimeters

BoxAppearance

Optional flow-box decoration, independent of typography and pagination.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
padding	Padding	nullable nonnegative millimeter padding; null means zero
borders	Borders	nullable independent physical edges; null means no borders
backgroundColor	String	nullable six-digit RGB color; null means transparent

BoxBlock

Rich flowing content with optional independent borders, padding and background color.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
blocks	List<Block>	owned nonempty content list, validated during generation
appearance	BoxAppearance	nullable physical decoration; null means undecorated
style	Style	nullable inherited typography and outer spacing/pagination overrides

CanvasBlock

A fixed-size flow unit containing arbitrary bounded elements in stable paint order. It consumes its declared height and moves to a following page as one unit when necessary. Native content overflow fails generation instead of clipping or shrinking the canvas.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
widthMm	double	positive finite canvas width, no larger than available width
heightMm	double	positive finite canvas height
elements	List<PositionedContent>	ordered owned element list with unique identifiers
style	Style	nullable inherited typography and outer spacing/pagination overrides

CellAppearance

Nullable cell appearance overrides. Each property inherits independently, first from table defaults and then from the legacy defaults. Text properties remain in the cell's Style.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
border	Border	optional uniform border, in points
padding	Padding	optional per-edge inner spacing, in millimeters
verticalAlignment	VerticalAlignment	optional content alignment
backgroundColor	String	optional six-digit RGB fill; null inherits the table fill

Column

Independent flowing content occupying a weighted share of its parent columns block.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
weight	double	positive finite proportional width, validated during generation
blocks	List<Block>	ordered owned content, required and nonempty during generation
style	Style	nullable inherited typography overrides

ColumnsBlock

Side-by-side independent rich-content columns, using proportional widths after physical gaps. The block flows to the height of its tallest column; content does not automatically continue from one column into another.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
columns	List<Column>	owned nonempty column list, checked during generation
gapMm	double	finite nonnegative gap between adjacent columns
style	Style	nullable inherited typography and outer spacing/pagination overrides

ComponentBlock

Reference to a document-local reusable component. Preparation replaces the reference with an ordinary group, applying reference styles below the component's own local block styles. JSON selects this record with type:"component".

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
name	String	registered component name, checked during generation
style	Style	nullable overrides inherited by the included content

DocumentMetadata

Optional descriptive PDF metadata; null fields omit the corresponding document information.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
title	String	document title
author	String	document author
subject	String	document subject
keywords	String	application-supplied keyword text

DocumentSettings

Optional language, formatting, metadata and explicit font fallback settings. No system-font scanning or JVM default locale/time zone participates.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
locale	LocaleSettings	country-aware formatting, null selects stable defaults
metadata	DocumentMetadata	optional PDF metadata
direction	TextDirection	optional explicit direction; null retains ordinary left-to-right behavior
fallbackFonts	List<String>	ordered registered family names, null becomes empty
hyphenate	Boolean	whether registered language patterns should be used, null means false

FixedElement

Positioned content repeated on selected pages inside a reserved top or bottom zone. Unlike body sections, fixed content cannot flow onto another page. Its bounds are relative to the selected zone, not the physical page or body origin. Generation requires unique nonblank identifiers, nonempty blocks, and bounds fitting the zone. Elements in the same zone may touch but must not overlap on any selected page. Page-break blocks are invalid here. Construction only snapshots the list.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
id	String	document-unique label used to identify the element
zone	Zone	reserved page region containing the element
pages	PageSelector	pages on which to repeat this content
boundsMm	Bounds	rectangle relative to the zone's upper-left corner, in millimeters
blocks	List<Block>	ordered region content; null is preserved for validation

GroupBlock

Ordered content grouped under common typography and a soft page-keep preference. An explicit keepTogether style overrides that preference. Group spacing applies around the container; pagination controls remain local. Explicit AUTO groups in body flow may contain page breaks.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
blocks	List<Block>	child blocks, snapshotted while preserving nulls for field-path validation
style	Style	nullable appearance and pagination overrides
defaultStyle	Style	nullable typography fallback below theme and explicit overrides

Heading

Text heading kept with the following block on the same page when layout permits. Before inherited overrides, headings default to bold 14-point Helvetica; ordinary text uses 11-point regular Helvetica. Generation requires a nonempty list of valid text runs.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
runs	List<TextRun>	ordered styled text; null is preserved for generation-time validation
style	Style	optional block overrides, layered after document and section styles
semanticStyle	Style	optional tag defaults, below theme and explicit local overrides

ImageBlock

PNG/JPEG/static SVG image scaled proportionally to fit an explicit box in millimeters. The rendered image participates in body flow or the containing positioned region. The block style controls alignment and surrounding spacing. Generation checks the MIME type, signature, decodability, positive finite dimensions, and available width. The constructor and #data() clone bytes, so callers cannot mutate stored image content. Equality and hashing use byte contents along with all other record components. The constructor itself does not validate the image.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
data	byte[]	encoded PNG/JPEG/static SVG bytes; null is retained for generation-time validation
mimeType	String	exact supported MIME type, image/png, image/jpeg or image/svg+xml
widthMm	Double	maximum rendered width in millimeters; required and positive at generation
heightMm	Double	maximum rendered height in millimeters; required and positive at generation
style	Style	nullable block overrides for alignment and spacing
altText	String	optional human-readable image description for tagged output

ImageWatermark

PNG/JPEG/static SVG image centered behind selected physical pages, with its aspect ratio preserved inside the supplied millimeter box. Watermark position is independent of page margins. Opacity ranges from zero to one; positive rotation turns counterclockwise about page center in PDF coordinates. The constructor copies image bytes but does not decode them or default null properties. Generation checks the MIME type, signature, decodability, positive finite box dimensions, page selection, opacity, and finite rotation. Factories detect image format and provide complete defaults. Stored bytes are protected by defensive copies on construction and access; equality and hashing compare their contents.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
data	byte[]	encoded PNG/JPEG/static SVG bytes, required during generation
mimeType	String	exact supported MIME type, image/png, image/jpeg or image/svg+xml
widthMm	Double	image fitting-box width in millimeters; required and positive during generation
heightMm	Double	image fitting-box height in millimeters; required and positive during generation
pages	PageSelector	page selection, required during generation
opacity	Double	finite paint opacity between zero and one, required during generation
rotationDegrees	Double	finite counterclockwise angle in degrees, required during generation

LetterComponent

Reusable immutable content registered on an individual document. References expand into ordinary groups before validation, retaining the group's soft keep unless explicitly overridden. Components may contain references to other registrations; generation rejects unknown names and cycles. No filesystem, network access or executable inclusion occurs.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
blocks	List<Block>	ordered component content, snapshotted while preserving invalid entries

LetterDocument

Complete immutable input to PDF generation, shared by the Java builders and JSON input. A document contains body sections, optional positioned content, a visual signature, and a watermark. The schema version is checked during generation; constructing this record does not validate content, fonts, geometry, or image formats. Supplied lists and the component map are copied into unmodifiable collections, preserving null entries for later validation. A null sections list remains null; only a null fixed-elements list becomes empty. Themes and reusable components resolve before ordinary validation, without global registrations.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
schemaVersion	int	input schema version; generation currently requires #SUPPORTED_SCHEMA_VERSION
page	PageSpec	physical layout, or null for PageSpec#defaults()
defaultStyle	Style	nullable overrides applied before section, block, cell, and run styles
sections	List<Section>	body sections in reading order; generation requires at least one body block
fixedElements	List<FixedElement>	positioned top/bottom content; null means no fixed elements
signature	Signature	optional visual signature; null means no signature
watermark	Watermark	optional decoration behind page content; null means no watermark
theme	LetterTheme	optional document-local role and named style defaults
components	Map<String, LetterComponent>	optional document-local reusable content; null becomes an empty map
settings	DocumentSettings	optional formatting and output metadata; null selects stable defaults
attachments	List<PdfAttachment>	optional PDFs appended unchanged after the generated letter

LetterPartBlock

Semantic letter content that receives element-specific theme defaults before ordinary layout.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
element	LetterElement	semantic role
blocks	List<Block>	ordered content, snapshotted
style	Style	optional local overrides

LetterTheme

Immutable per-document role defaults and named styles. Theme values never modify global state. Each nullable style property inherits independently; explicit document, section and content overrides take precedence over role defaults. Named styles may reference another named style through Style#styleName(); generation rejects unknown names and cycles.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
roles	Map<StyleRole, Style>	role defaults; null means no role overrides
namedStyles	Map<String, Style>	reusable named overrides; null means no named styles
tableAppearance	TableAppearance	optional table geometry/paint defaults
stationery	Stationery	optional repeating region defaults

ListBlock

Ordered or bulleted list with one sequence of text runs per item. Ordered labels start at 1; unordered labels are bullets. Items are kept together on a page when possible. Generation requires at least one item and at least one valid text run in every item.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
items	List<List<TextRun>>	item content in display order; null outer/inner lists are preserved for validation
ordered	boolean	true for numbered labels, false for bullets
style	Style	optional list style inherited by each item and its runs
contentItems	List<ListItem>	optional hierarchical items; supply this or legacy items, never both

ListItem

A list item's literal inline content followed by zero or more nested ordered/bulleted lists. Child lists inherit the containing list's typography and indent relative to this item's body.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
runs	List<TextRun>	owned inline content, required and nonempty during generation
children	List<ListBlock>	owned nested lists; null means no child lists

LocaleSettings

Deterministic per-document formatting, independent of JVM defaults.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
languageTag	String	BCP 47 locale; null defaults to en-GB
datePattern	String	optional explicit date pattern
dateStyle	FormatStyle	localized date style; null means LONG
currencyCode	String	optional ISO currency code; otherwise derived from the locale country
zoneId	String	explicit time zone; null means UTC

Margins

Physical-page insets in millimeters, outside both the body and reserved zones. Construction stores values unchanged; generation requires finite nonnegative margins and usable page width and height after margins and zones are removed.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
top	double	inset from the physical page's top edge, in millimeters
right	double	inset from the physical page's right edge, in millimeters
bottom	double	inset from the physical page's bottom edge, in millimeters
left	double	inset from the physical page's left edge, in millimeters

Padding

Cell inner spacing, in millimeters. Each value must be finite and nonnegative at generation.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
topMm	double	space inside the top edge
rightMm	double	space inside the right edge
bottomMm	double	space inside the bottom edge
leftMm	double	space inside the left edge

PageBreakBlock

Explicit page boundary in the body flow. Generation rejects this block in fixed elements and visual signatures. It has no style or text and does not create a new section.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints

This variant has no additional fields.

PageDimensions

Custom physical paper dimensions, validated during generation.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
widthMm	double	positive finite edge in millimeters
heightMm	double	positive finite edge in millimeters

PageSpec

Physical page layout with reserved regions inside the page margins. The top zone is above the body and the bottom zone is below it. On the last page, the signature zone sits above the bottom zone and reduces the available body height by its own height, even if no signature is supplied. All zones span the width remaining between left/right margins. The constructor replaces nulls with defaults but does not check dimensions. Generation requires finite nonnegative margins/zones and positive body space on ordinary and last pages.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
size	PageSize	portrait paper size; null becomes PageSize#A4
marginsMm	Margins	outer page insets; null becomes 20 mm on every side
topZoneMm	Double	reserved height above body content, in millimeters; null becomes zero
bottomZoneMm	Double	reserved height below body content, in millimeters; null becomes zero
signatureZoneMm	Double	additional reserved last-page height above the bottom zone, in millimeters; null becomes zero
dimensions	PageDimensions	optional custom paper edges in millimeters
orientation	Orientation	optional orientation; null means PORTRAIT

Paragraph

Flowing literal text that can wrap and continue across pages. Text runs retain their order, spaces, and line feeds; they are not parsed as HTML. Generation requires a nonempty run list with nonnull text and supported style/font values.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
runs	List<TextRun>	ordered styled text; null is preserved for generation-time validation
style	Style	optional block overrides, layered after document and section styles

PdfAttachment

Owned, validated PDF pages to append after a generated letter. Encrypted and empty PDFs are rejected; equality and hashing compare encoded contents. Attachments are accepted only by the standard output profile because merging arbitrary PDFs cannot preserve profile guarantees.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
data	byte[]	complete unencrypted PDF bytes, copied on construction and access

PositionedContent

One stable, bounded canvas element. Coordinates are millimeters from its canvas's top-left; content order controls painting order, so later elements may overlap earlier ones.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
id	String	nonblank identifier unique within its canvas, checked at generation
boundsMm	Bounds	positive rectangle wholly inside the canvas, checked at generation
blocks	List<Block>	owned ordered content; page breaks are forbidden at any nesting level
style	Style	nullable inherited typography overrides

Section

Named group of body blocks rendered in list order. Sections do not force page breaks or select physical page regions; the name is a descriptive label. Style properties inherit from the document and are overridden by individual blocks and text runs.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
name	String	section label; generation requires nonblank XML-compatible text
style	Style	optional section overrides, or null to inherit the document style
blocks	List<Block>	body content; null is preserved for generation-time validation

Signature

Visual signature content, either appended to the body or positioned on the final page. This is rendered letter content, not a cryptographic PDF signature. FLOW requires null bounds; BOTTOM_LAST requires bounds inside a positive-height zone. Page-break blocks are invalid in both modes.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
placement	SignaturePlacement	flowing or final-page placement; required during generation
blocks	List<Block>	nonempty signature content; null is retained for generation-time validation
boundsMm	Bounds	zone-relative rectangle in millimeters for BOTTOM_LAST, or null for FLOW

Stationery

Immutable header, footer and logo geometry shared by letters using a theme. Geometry is relative to the inner page rectangle; choose the same paper and margins when authoring the stationery. Letter-local regions with the same stable identifier replace inherited regions.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
elements	List<FixedElement>	fixed top/bottom elements, defensively snapshotted
topZoneMm	double	reserved top height including the desired body gap
bottomZoneMm	double	reserved bottom height including the desired body gap

Style

Immutable set of nullable typography and spacing overrides. Null means inherit that property; an explicit false disables an inherited boolean flag. During rendering, built-in text defaults are overlaid by document, section, block, optional table-cell, and text-run styles in that order. Fixed regions and signatures have no section style. A named reference selects per-document theme overrides below this style's explicit properties. Built-in text defaults are Helvetica, 11 pt (14 pt and bold for headings), black, left alignment, a 1.2 line-height multiplier, and zero space before/after. The other flags are false. #plain() has no overrides and therefore preserves those or any inherited values; it does not reset text to the built-in defaults. Construction and builder methods do not validate values. Generation requires registered or built-in font families and available bold/italic variants, positive finite font sizes and line-height multipliers, finite nonnegative spacing, and colors in #RRGGBB form.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
fontFamily	String	built-in or registered family name, or null to inherit
fontSizePt	Double	font size in points (1/72 inch), or null to inherit
color	String	six-digit hexadecimal RGB text color, or null to inherit
bold	Boolean	bold flag, or null to inherit
italic	Boolean	italic flag, or null to inherit
underline	Boolean	underline flag, or null to inherit
textAlign	TextAlign	horizontal paragraph alignment, or null to inherit
lineHeight	Double	dimensionless multiplier of font size, or null to inherit
spaceBeforeMm	Double	spacing before the block in millimeters, or null to inherit
spaceAfterMm	Double	spacing after the block in millimeters, or null to inherit
keepTogether	Keep	page keep for this block, or null for its ordinary policy
keepWithNext	Keep	page keep with the next block, or null for its ordinary policy
widows	Integer	minimum trailing paragraph lines on a page, positive or null
orphans	Integer	minimum opening paragraph lines on a page, positive or null
styleName	String	optional reference to a named style in the document theme
baseStyle	Style	optional lower-priority layer, resolved before the named style and local fields; retains the order of nested styles until document-local names can be resolved

TableAppearance

Table appearance defaults shared by every authoring API. Explicit table and cell settings win.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
cells	CellAppearance	defaults for every cell
header	CellAppearance	additional repeating-header defaults
rowKeepTogether	Keep	default row pagination policy

TableBlock

Full-width native table with positive proportional column weights, an optional repeating header and ordered body rows. Cells can span columns/rows; each section must cover its complete grid without holes or overlap, and header spans cannot enter the body. Cell text inherits table, cell and run styles in that order. Rich cells also support ordinary paragraphs, lists and images.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
columnWeights	List<Double>	positive relative weights, one per physical column
header	List<TableCell>	optional single repeating header row, null becomes empty
rows	List<List<TableCell>>	ordered body rows containing cells at their first unoccupied column
style	Style	nullable table typography and spacing
options	TableOptions	optional appearance and row policies; null preserves legacy defaults

TableCell

Cell containing either inline runs or ordinary blocks. Runs retain the compact legacy form; blocks support paragraphs, headings, lists and images, with no nested tables or page breaks. Exactly one form must be supplied. An empty block list explicitly represents an empty visual cell. Span and appearance checks occur during generation.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
runs	List<TextRun>	optional nonempty ordered inline content; exclusive with blocks
style	Style	nullable typography layered after the table style
backgroundColor	String	legacy optional six-digit RGB fill, overriding appearance fill
blocks	List<Block>	optional block content; an empty list creates an empty cell
columnSpan	Integer	optional positive column span, null means one
rowSpan	Integer	optional positive row span, null means one
appearance	CellAppearance	optional cell appearance overrides
semanticStyle	Style	optional tag defaults below themes and explicit cell styles
defaultAppearance	CellAppearance	optional semantic appearance below theme and explicit table defaults

TableOptions

Optional table appearance and body-row page policies. Absent options retain one-millimeter padding, white quarter-point borders, centered content and a soft keep on every row.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
cellAppearance	CellAppearance	optional defaults inherited independently by every cell
rowKeepTogether	Keep	optional default row split control, null means PREFER
rowPolicies	List<TableRowPolicy>	optional body-row overrides, null becomes empty
rowGroups	List<TableRowGroup>	optional disjoint body-row groups, null becomes empty

TableRowGroup

Consecutive body rows requested to stay on one page. Groups cannot overlap and cannot include header rows. A soft preference may break when necessary; an impossible strong keep can fail.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
startRow	int	first zero-based body row index
rowCount	int	positive number of rows in the group
keepTogether	Keep	required keep strength, including AUTO to allow normal breaks

TableRowPolicy

Overrides page-breaking behavior for one zero-based body row. Indices must be unique and in range.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
rowIndex	int	body row index, starting at zero
keepTogether	Keep	optional row split control; AUTO allows splitting
keepWithNext	Keep	optional relationship to the following body row

TextRun

Literal inline text with optional style overrides and an external hyperlink. Text is XML-escaped during rendering, and spaces and line feeds are preserved by text blocks; it is never interpreted as HTML markup. Styles apply after the containing block or cell. Construction performs no validation. Generation permits empty text but requires nonnull XML-compatible text. A supplied link must be a syntactically valid absolute HTTP, HTTPS, or mailto URI with a nonempty scheme-specific part; HTTP(S) links also require a host.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
text	String	literal text, including any spaces or line feeds
style	Style	optional run-level overrides, or null to inherit from the block or cell
href	String	external hyperlink target, or null for unlinked text
pageNumber	PageNumber	optional dynamic page field; text must be empty when supplied

TextWatermark

Text centered behind selected pages using a built-in or registered regular font. Positioning uses the physical page center, independently of margins and reserved zones. Text size uses points; rotation is about the page center and positive angles rotate counterclockwise in PDF coordinates. Opacity ranges from zero (invisible) to one (opaque). The canonical constructor stores every value unchanged; nulls do not select defaults. Generation requires nonblank XML-compatible text, a supported family, positive finite size, a #RRGGBB color, nonnull page selection, opacity in [0, 1], and finite rotation. Use #of(String) for a complete set of default appearance values.

Java contract and constructors ↗

JSON field	Value type	Meaning and constraints
text	String	literal watermark text, required and nonblank during generation
fontFamily	String	built-in or registered regular font family; required during generation
fontSizePt	Double	font size in points (1/72 inch); required and positive during generation
color	String	six-digit hexadecimal RGB text color, required during generation
pages	PageSelector	page selection, required during generation
opacity	Double	finite paint opacity between zero and one, required during generation
rotationDegrees	Double	finite counterclockwise angle in degrees, required during generation

Enum values

JSON enum values are case-sensitive strings. Null selects inheritance/defaults only where the owning field allows it.

BorderStyle

NONE, SOLID, DASHED, DOTTED

Enum contract ↗

FormatStyle

FULL, LONG, MEDIUM, SHORT

Enum contract ↗

Keep

AUTO, PREFER

Enum contract ↗

LetterElement

SENDER, DATE, RECIPIENT, REFERENCE, SUBJECT, SALUTATION, CLOSING

Enum contract ↗

Orientation

PORTRAIT, LANDSCAPE

Enum contract ↗

PageNumber

CURRENT, TOTAL

Enum contract ↗

PageSelector

FIRST

Enum contract ↗

PageSize

A4, LETTER

Enum contract ↗

SignaturePlacement

Enum contract ↗

StyleRole

BODY, HEADING, TABLE, TABLE_HEADER, TABLE_CELL, HEADER, FOOTER, SIGNATURE, SENDER, RECIPIENT, DATE, SUBJECT, REFERENCE, SALUTATION, CLOSING

Enum contract ↗

TextAlign

LEFT, CENTER, RIGHT, JUSTIFY

Enum contract ↗

TextDirection

AUTO, LTR, RTL

Enum contract ↗

VerticalAlignment

TOP

Enum contract ↗

Zone

TOP

Enum contract ↗