We’re pleased to announce the release of GroupDocs.Assembly for Java 26.11, available as of November 2026. This release brings the features and fixes of GroupDocs.Assembly for .NET 26.11 to Java:
- templates can be checked against a JSON Schema;
- pages of templates and reports can be rendered to images;
- loading of external resources is under the control of the application;
REMOVE_EMPTY_PARAGRAPHSworks for spreadsheet and plain text templates;<<image>>tags work in table cells of presentations and resolve relative paths against the template folder;- color tags accept hex strings.
The bundled Aspose engines move from their early 2026 versions to 26.10, and a number of fixes cover licensing, report encoding, barcodes and HTML content. Java 8 remains the baseline.
What’s new in this release
| Key | Summary | Category |
|---|---|---|
| ASSEMBLYNET-145 | JsonDataSource accepts a JSON Schema: members declared in the schema can be referenced even when they are null, empty or missing in the data, and value types come from the schema |
Feature |
| ASSEMBLYNET-8 | DocumentAssembler.generatePreview renders pages of templates, assembled reports and other documents to PNG, JPEG or BMP images |
Feature |
| ASSEMBLYNET-36, ASSEMBLYNET-37 | DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS works for spreadsheet templates and plain text documents |
Feature |
| ASSEMBLYNET-140 | External resources referenced by templates and data are under the control of the application; resources whose references come from data are skipped by default | Security |
| ASSEMBLYJAVA-353 | Aspose.Words 26.10.1, Aspose.Cells 26.10, Aspose.Slides 26.10, Aspose.Email 26.9 and Aspose.BarCode 26.10 are bundled | Update |
| ASSEMBLYJAVA-353 | GS1 barcodes (EAN-14, SCC-14, SSCC-18 and DataBar) keep the auto-correction of their code text with Aspose.BarCode 26.10 | Fix |
| ASSEMBLYNET-52 | An <<image>> tag works in a table cell of a presentation, and tags in shapes of group shapes are processed |
Enhancement |
| ASSEMBLYNET-62 | A relative image path from data is resolved against the folder of the template | Enhancement |
| ASSEMBLYNET-25 | A color given as a string can be a hex value in backColor and chart color tags |
Enhancement |
| ASSEMBLYNET-155 | A missing Boolean of JSON, XML or CSV data counts as false in ?: and in where, count, any, all and first instead of failing |
Fix |
| ASSEMBLYNET-157 | groupBy and distinct over nested objects merge equal objects; $id/$ref references of JSON data are supported |
Fix |
| ASSEMBLYNET-142 | License.setLicense(InputStream) reads a stream that has already been read from its beginning |
Fix |
| ASSEMBLYNET-143 | Consumption of a metered license is reported when an operation completes | Fix |
| ASSEMBLYNET-158 | Text and HTML reports of ASCII-only templates are written in UTF-8, so non-Latin data is no longer lost | Fix |
| ASSEMBLYNET-160 | Barcodes no longer fail with NullPointerException when the font of their text box is not installed |
Fix |
| ASSEMBLYNET-159 | Tags in the conversation topic of an MSG template are assembled like those of its subject | Fix |
| ASSEMBLYNET-152 | A <<doc>> tag in a spreadsheet, presentation or text template fails with a clear message; a failed assembleDocument leaves no empty output file |
Fix |
| ASSEMBLYJAVA-354 | An -html expression tag ending its paragraph no longer leaves an empty paragraph after HTML ending with a block element |
Fix |
Behaviour changes to check before upgrading
- External resources from data are skipped by default. For example,
<<image [item.PhotoUrl]>>wherePhotoUrlis an http or https URI now gives an empty image. Add the hosts toLoadSaveOptions.getWhitelistedResources(), or callLoadSaveOptions.setSkipExternalResources(false)to keep the previous behaviour. Resources referenced by the template itself and local file paths work as before. - Ambiguous
JsonDataSourcecall.new JsonDataSource(path, null)with a literalnullsecond argument no longer compiles. Cast the argument:new JsonDataSource(path, (JsonDataLoadOptions) null). Compiled applications are not affected. - UTF-8 text and HTML reports. Reports of ASCII-only text and HTML templates without a byte order mark are now written in UTF-8 instead of windows-1252. To keep a single-byte code page, declare it in the template (
<meta charset>in HTML). groupByanddistinctover nested objects of JSON, XML and DataSet data now merge equal objects instead of giving one group per row.- No extra paragraph after HTML. An
-htmltag ending its paragraph no longer leaves an empty paragraph after HTML ending with a block element. To keep a blank line, end the HTML with<p> </p>. - DataBar Expanded barcodes. A DataBar Expanded or DataBar Expanded Stacked barcode with a code text of digits only is now encoded as a GTIN with the (01) application identifier, like the other DataBar types.
- Changed exception text for a
<<doc>>tag in spreadsheet, presentation and text templates; the exception type is the same. - Removed API.
ICustomFontsHandler.resetFontSources()is removed; callFontSettings.resetFontSources()instead.
New features
JSON Schema support for JsonDataSource
A template is checked against the structure of its data before any <<if>> is evaluated. With JSON, that structure used to be taken from the data itself, so a reference inside a branch that never renders failed when the data behind it was null, an empty array or missing.
JsonDataSource now accepts a JSON Schema, the same way XmlDataSource accepts an XML Schema, and the template is checked against the schema:
- members declared in the schema can be referenced even if they are null, empty or absent in the data;
- members not declared in the schema still fail, so misspelled names are detected as before;
- value types come from the schema, so a boolean is a
Booleanand a string holding digits stays a string.
Given a customer with no payment cards and no loyalty data, and an account number that is a string of digits:
{ "Name": "Quayside Bistro", "Account": "00042", "Cards": [], "Loyalty": null }
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"Name": { "type": "string" },
"Account": { "type": "string" },
"Cards": {
"type": "array",
"items": { "type": "object", "properties": { "Type": { "type": "string" }, "Last4": { "type": "string" } } }
},
"Loyalty": { "type": ["object", "null"], "properties": { "Level": { "type": "string" } } }
}
}
and this template:
Customer: <<[customer.Name]>>
Account number: <<[customer.Account]>>
<<if [customer.Cards.count() > 0]>>Payment card: <<[customer.Cards.first().Type]>> ending in <<[customer.Cards.first().Last4]>><<else>>No payment card on file.<</if>>
Loyalty program: <<[customer.Loyalty?.Level]>>
pass the schema next to the data:
JsonDataSource dataSource = new JsonDataSource("Customer.json", "Customer.schema.json");
DocumentAssembler assembler = new DocumentAssembler();
assembler.assembleDocument("Json schema.docx", "output.docx", new DataSourceInfo(dataSource, "customer"));
The result is No payment card on file. with the account number 00042. Without the schema, the same template fails on customer.Cards.first().Type, and the account number is read as the number 42.
The schema can be given as a file path or an InputStream, with or without JsonDataLoadOptions. Supported keywords are type (including nullable types), properties, items, format (date-time and date), enum, const, allOf and local $ref pointers. oneOf, anyOf, not, remote or recursive $ref, tuple-form items and arrays of arrays are not supported.
Document preview
DocumentAssembler.generatePreview renders pages of a document to PNG, JPEG or BMP images: a template, a document assembled by GroupDocs.Assembly, or any other document of a supported format, from a file or a stream. Pages of word processing, text and HTML documents, printed pages of spreadsheets, slides of presentations and email messages with their header are rendered.
DocumentAssembler assembler = new DocumentAssembler();
ByteArrayOutputStream report = new ByteArrayOutputStream();
try (InputStream template = new FileInputStream("Customer orders.docx"))
{
assembler.assembleDocument(template, report,
new DataSourceInfo(new JsonDataSource("Customers.json"), "customers"));
}
// A stream is created for every page and released when the page is written.
PreviewOptions options = new PreviewOptions(
pageNumber -> new FileOutputStream("page" + pageNumber + ".png"),
(pageNumber, pageStream) -> pageStream.close());
options.setPreviewFormat(PreviewFormats.PNG);
options.setResolution(120); // dots per inch; 96 by default
// options.setPageNumbers(new int[] { 1, 2 }); // all pages by default
assembler.generatePreview(new ByteArrayInputStream(report.toByteArray()), options);
When both setWidth and setHeight are set, pages are scaled to fit that size keeping their aspect ratio. Previews are generated without loading any external resources, and generated images are counted by metered licensing like assembled documents.
REMOVE_EMPTY_PARAGRAPHS for spreadsheet and plain text templates
DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS now works for spreadsheet templates and plain text documents as well. There, a paragraph is a line of text: a line of a cell’s text, or of a text document, that becomes empty after template tags are processed is removed together with its line break. Tags such as <<if>> and <<foreach>> written on their own lines no longer leave empty lines behind.
DocumentAssembler assembler = new DocumentAssembler();
assembler.setOptions(DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS);
assembler.assembleDocument("Empty paragraph.txt", "result.txt", new DataSourceInfo("dummy", "dummy"));
Template:
Prefix
<<if [false]>>
Text to be removed
<</if>>
Suffix
Result:
Prefix
Suffix
The same template text in a spreadsheet cell gives the same result within the cell. HTML and XML documents stay as they are.
Security: control of external resources
An <<image>> or <<doc>> tag can evaluate to a URI taken from the data, and GroupDocs.Assembly used to fetch it with no way to prevent it. A server assembling documents from data supplied by others could thus be made to request internal addresses.
GroupDocs.Assembly now tells where each reference to an external resource comes from (ExternalResourceOrigin):
TEMPLATE— the template document references the resource itself, including a literal URI in a tag such as<<image ["https://example.com/logo.png"]>>;DATA— the reference comes from data, such as a URI a tag expression evaluates to.
By default, resources referenced by the template are loaded as before, and resources whose references come from data are skipped. Four members of LoadSaveOptions control this:
setSkipExternalResources(trueby default) — external resources are not loaded;setTrustTemplateResources(trueby default) — resources referenced by the template are loaded even when skipping is on; set it tofalsewhen templates come from untrusted sources;getWhitelistedResources— host names or absolute URI prefixes allowed even when skipping is on;setExternalResourceHandler— anExternalResourceHandlercalled for every external resource before it is requested, to allow it, skip it or provide its content.
final String photoUri = "https://images.example.com/photos/no-photo.jpg";
DocumentAssembler assembler = new DocumentAssembler();
// Default options: the URI comes from data, so the image is skipped and left empty.
assembler.assembleDocument("Inserting image.docx", "Skipped.docx", new DataSourceInfo(photoUri, "expression"));
// Allow a trusted host and see every decision. The handler can also provide the content itself.
LoadSaveOptions options = new LoadSaveOptions();
options.getWhitelistedResources().add("images.example.com");
options.setExternalResourceHandler(new LocalImageHandler("no-photo.jpg"));
assembler.assembleDocument("Inserting image.docx", "Provided.docx", options, new DataSourceInfo(photoUri, "expression"));
public class LocalImageHandler extends ExternalResourceHandler
{
private final String mImagePath;
public LocalImageHandler(String imagePath) { mImagePath = imagePath; }
@Override
public void onLoading(ExternalResourceLoadingArgs args)
{
System.out.println(ExternalResourceOrigin.toString(args.getOrigin()) + " resource " + args.getUri() + ": "
+ (args.isSkipped() ? "skipped" : "allowed"));
// Provide the content instead of requesting it.
if (!args.isSkipped() && args.getUri().toLowerCase().startsWith("https://images.example.com/"))
{
try
{
args.setData(Files.readAllBytes(Paths.get(mImagePath)));
}
catch (IOException e)
{
throw new UncheckedIOException(e);
}
}
}
}
External resources are resources reaching the network: http, https and ftp URIs, UNC paths and file URIs with a remote host. Local file paths are not affected. A skipped image of a document is replaced with a transparent image; a skipped <<image>> or <<doc>> value is treated as an empty value.
Enhancements
Images in table cells and group shapes of presentations
In a presentation template, an <<image>> tag could only be placed in a text box. A table cell is now an image container too: the image becomes the picture fill of the cell, including cells of rows repeated by <<foreach>>, so a table listing items with their pictures can be built. With -fitHeight, the row grows to show the image with its aspect ratio. Tags in shapes of group shapes, including nested groups, are now processed like other shapes.
Relative image paths resolved against the template folder
An <<image>> tag that gets a relative file path from data, such as Images/photo.png, now resolves it against the folder of the template first, by analogy with linked resources of Microsoft Office documents. For a template loaded from a stream, set the folder with LoadSaveOptions.setResourceLoadBaseUri:
DocumentAssembler assembler = new DocumentAssembler();
// A template loaded from a stream has no folder: set it with setResourceLoadBaseUri.
LoadSaveOptions options = new LoadSaveOptions();
options.setResourceLoadBaseUri("C:\\Reports\\Templates");
try (InputStream template = new FileInputStream("C:\\Reports\\Templates\\Inserting image.docx");
OutputStream report = new FileOutputStream("output-from-stream.docx"))
{
assembler.assembleDocument(template, report, options, new DataSourceInfo("../Images/no-photo.jpg", "expression"));
}
If no file exists there, the current directory is used as before.
Hex color strings
A color given as a string can now be a hex value — "#RRGGBB", "#RGB" or "#AARRGGBB" — in addition to a color name and an ARGB integer, in backColor and chart color tags. For example, <<backColor [item.Color]>> with "#FF0000" coming from data now applies red.
Fixes
- Missing Booleans of JSON, XML and CSV data now count as
falsein the conditional operator?:and in the predicates ofwhere,count,any,allandfirst, instead of failing with aNullPointerException. groupByanddistinctover nested objects of JSON and XML data compare objects by value, so equal customers make one group. JSON written with preserved references ($id/$ref) is now supported.License.setLicense(InputStream)reads aByteArrayInputStreamfrom its mark and aFileInputStreamfrom position 0, so a stream already used to license another GroupDocs product no longer fails with “Unexpected EOF in prolog”.- Metered consumption is reported when assembling a document or generating a preview completes, instead of later from a background thread.
- Text and HTML reports of ASCII-only templates are written in UTF-8, so data such as
CaféorПриветis no longer lost to windows-1252. - Barcodes whose code text is drawn by the engine (QR, DataMatrix, Aztec and others) no longer fail when the font of their text box is not installed — typically Calibri on Linux. A fallback font is used instead.
- MSG templates: tags in the conversation topic are processed like those of the subject, so Outlook threads the messages correctly.
<<doc>>in spreadsheet, presentation and text templates fails with a message saying the tag is not supported for the format, and a failedassembleDocumentno longer leaves an empty output file.- HTML content: an
-htmlexpression tag ending its paragraph no longer leaves an extra empty paragraph after HTML ending with a block element (ASSEMBLYJAVA-354). - GS1 barcodes: GroupDocs.Assembly now corrects digit-only code texts of EAN-14, SCC-14, SSCC-18 and DataBar barcodes itself, because Aspose.BarCode 26.10 stopped doing it, so these barcodes stay the same as in 26.10.1.
Aspose engines upgraded to 26.10
GroupDocs.Assembly for Java 26.10.1 bundled Aspose libraries from early 2026, so vulnerabilities fixed in them since then were reported by security scanners. The bundled engines are now:
| Engine | 26.10.1 | 26.11 |
|---|---|---|
| Aspose.Words for Java | 26.3 | 26.10.1 |
| Aspose.Cells for Java | 26.3 | 26.10 |
| Aspose.Slides for Java | 26.2 | 26.10 |
| Aspose.Email for Java | 26.1 | 26.9 |
| Aspose.BarCode for Java | 26.6 | 26.10 |
The published POM still declares no dependencies. Because the engines were refreshed, regenerated documents may differ at the byte level while remaining visually and functionally equivalent. If you byte-compare generated output against stored baselines, refresh those baselines after upgrading.
Notes for Java users
- Dates with
Zor an offset in JSON or CSV data arejava.util.Datevalues of that exact instant, and a format pattern prints them in the JVM’s default time zone. For output that doesn’t depend on the server, run the JVM with a fixed time zone, for example-Duser.timezone=UTC. ExternalResourceOriginandPreviewFormatsare classes ofintconstants, like the other enumerations of the Java API.CreatePageStreamandReleasePageStreamare functional interfaces, so lambdas fit.
How to get the update
Maven
Add the GroupDocs repository and the dependency to your pom.xml:
<repositories>
<repository>
<id>groupdocs-artifacts-repository</id>
<name>GroupDocs Artifacts Repository</name>
<url>https://releases.groupdocs.com/java/repo/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-assembly</artifactId>
<version>26.11</version>
</dependency>
</dependencies>
Direct download
Download the JAR from the GroupDocs.Assembly for Java 26.11 download page.