JSON input

Complete first integration

The following input and Java runner are the exact resources used by the documentation integration test. Save the input under src/main/resources/letters/hello.json, or download the complete runnable Maven project.

{
  "schemaVersion": 1,
  "sections": [{
    "name": "body",
    "blocks": [{
      "type": "paragraph",
      "runs": [{ "text": "Hello from Letter Generator" }]
    }]
  }]
}

import com.nsdev.lettergenerator.LetterPdfGenerator;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

/** Render a strict JSON resource with the same defaults as Java construction. */
public final class JsonQuickstart {
    private JsonQuickstart() {}

    public static void main(String[] args) throws Exception {
        String source;
        try (var stream = JsonQuickstart.class.getResourceAsStream("/letters/hello.json")) {
            if (stream == null) {
                throw new IllegalStateException("Missing /letters/hello.json resource");
            }
            source = new String(stream.readAllBytes(), StandardCharsets.UTF_8);
        }
        byte[] pdf = new LetterPdfGenerator().generateJson(source);
        Files.write(Path.of(args.length == 0 ? "letter.pdf" : args[0]), pdf);
    }
}

Letter.fromJson(source) parses a shared document model; generateJson(source) renders to bytes and renderJson(source, options) adds output choices and a rendering report. Parsing alone does not validate semantic requirements or establish layout fit. The JSON literal null can parse to a null model, which generation rejects.

Use the complete JSON field/enum reference for all reachable document types and discriminators. JSON does not perform placeholder substitution or include HTML directives; supply the final structural model.

byte[] pdf = generator.generateJson(Files.readString(Path.of("letter.json")));

Minimal JSON:

{
  "schemaVersion": 1,
  "sections": [{
    "name": "body",
    "blocks": [{
      "type": "paragraph",
      "runs": [{"text": "Olá João, request received."}]
    }]
  }]
}

Letter.fromJson(json) parses JSON into the shared model for validate(...), copy methods or render(...). generator.renderJson(json[, options]) returns the same rendering report and profile choices as the other APIs. generateJson(json) retains the byte-only standard path. JSON maps to the immutable model, not the HTML template format. It has no placeholder substitution pass. Enums use uppercase names. Block type values are paragraph, heading, list, image, table, pageBreak, group, component, letterPart, canvas, columns and box; watermark kind is text or image. Image data is Base64. Unknown fields/discriminators, duplicate keys, malformed JSON, trailing documents, scalar coercion, numeric enum ordinals and fractional schema versions are rejected.

Optional model fields may be omitted or null and use their documented defaults. Required fields produce a field-path error. See the model constructor reference and public records for full structured input. Do not treat external Java class names as JSON discriminators.

Structured list, table and watermark examples

A list block contains an array of items, each represented by an array of text runs:

{"type":"list","ordered":true,"items":[[{"text":"First"}],[{"text":"Second"}]]}

A table block can specify styles and backgrounds per cell:

{"type":"table","columnWeights":[2,1],
 "header":[
   {"runs":[{"text":"Component"}],"backgroundColor":"#10384A","style":{"color":"#FFFFFF"}},
   {"runs":[{"text":"Price"}],"backgroundColor":"#10384A","style":{"color":"#FFFFFF"}}],
 "rows":[[
   {"runs":[{"text":"Energy (€/kWh)"}]},
   {"runs":[{"text":"0,1632"}]}]]}

For a text watermark, put this object in the document’s watermark property:

{"kind":"text","text":"DRAFT","fontFamily":"Helvetica","fontSizePt":60,
 "color":"#808080","pages":"ALL","opacity":0.2,"rotationDegrees":35}

An image watermark uses Base64 bytes and an explicit millimeter box:

{"kind":"image","data":"BASE64_PNG_OR_JPEG","mimeType":"image/png",
 "widthMm":80,"heightMm":40,"pages":"FIRST","opacity":0.15,"rotationDegrees":10}

Links permit http, https and mailto. Document text is escaped before internal FO construction; external XML entity loading and document-controlled filesystem/network resource access are disabled.