Hi ,
We are encountering an unexpected issue when formatting dates using the LINQ Reporting Engine in Aspose.Words for Java (tested across versions 25.3 to 25.6).
Specifically, when using the “dd/MM/yyyy” directive in the template, one ISO 8601 date field formats correctly, while another — also in valid ISO format — does not. Both input values are structured identically, yet only one of them renders the expected output format.
Could you please investigate and advise why this inconsistency occurs? date_issue.zip (31.7 KB)
The issue you’re experiencing with date formatting in the LINQ Reporting Engine likely arises from differences in how the date values are interpreted or processed, despite appearing identical in ISO 8601 format. This can occur due to variations in the underlying data types or the manner in which the dates are passed to the reporting engine.
Solution
To troubleshoot this inconsistency, follow these steps:
Check Data Types: Ensure that both date fields are treated as the same data type in your data source. One may be a string while the other is a date object.
Inspect Input Values: Verify that both date values are formatted correctly and are valid ISO 8601 dates. Log or print the values before processing them.
Use Explicit Formatting: Instead of relying solely on the template directive, format the dates explicitly in your code before passing them to the template to ensure consistency.
Test with Simplified Data: Create a minimal example with just the two date fields to isolate the issue and determine if external factors are affecting the formatting.
Code
Here’s a simple example of how to format the date explicitly in your Java code before passing it to the template:
import java.text.SimpleDateFormat;
import java.util.Date;
Date date1 = // your first date
Date date2 = // your second date
SimpleDateFormat formatter = new SimpleDateFormat("dd/MM/yyyy");
String formattedDate1 = formatter.format(date1);
String formattedDate2 = formatter.format(date2);
// Pass formattedDate1 and formattedDate2 to your template
Next Steps
After implementing the above suggestions, test the output again. If the issue persists, please share a minimal reproducible example or the specific data causing the problem for further investigation. I look forward to your feedback!
We are using an external JSON data source over which we do not have control. The input date values are provided as ISO 8601 strings (e.g., "2025-07-23T05:22:08.980Z"), and we are passing them directly to the LINQ Reporting Engine.
Converting these strings to Date objects in code before passing them to the template is not a desirable solution, as we aim to keep the templating layer self-contained and data-driven.
Given that the LINQ engine successfully formats some ISO date strings but not others — even though they follow the same format — we suspect this may be an inconsistency in how the engine interprets string-based dates internally. Could you please test and provide your guidance.
Our attention shifted to the date data within the JSON payload, where a critical observation was made: Aspose Words Java consistently parsed dates correctly when their milliseconds component was less than 600. However, when the milliseconds value was 600 or greater, it failed to process the date as expected, instead outputting the entire date string literally.
@sagaofsilence.dev Unfortunately, the problem is still not reproducible on my side using the latest 25.7 version of Aspose.Words for Java. the same code as provided above was used for testing. Here are input and output documents: in.docx (14.5 KB) out.docx (11.8 KB)
@sagaofsilence.dev I also tested our scenario on Windows machine. Could you please attach your actual input, output and json used for testing along with code your use? We will check the scenario with your actual documents and provide you more information.
Many thanks for clarifying the OS used for testing. This valuable information confirms there’s no runtime discrepancy from that angle. We can now direct our efforts back to the service implementation to meticulously investigate and isolate the true root cause.
We are currently implementing our service using Aspose Words for Java v25.5 and are seeking clarification on date formatting behavior within templates.
The official Aspose documentation for Java, specifically the section on “Outputting Expression Results” (Outputting Expression Results in Java|Aspose.Words for Java), states that date-time format strings should align with those used by SimpleDateFormat formatters. An example provided is <<[d]:"yyyy.MM.dd">>.
There is also .NET-styled date format strings, as detailed in Microsoft’s documentation (Custom date and time format strings - .NET | Microsoft Learn). A notable difference is in the representation of milliseconds: SimpleDateFormat uses “SSS”, while .NET uses “FFF” or “fff”.
The JsonDataLoadOptions.setExactDateTimeParseFormats method also exists. If my date data is in ISO UTC format, do I need to set up these data options?
For the data "C$CreatedAt1": "2025-05-02T03:17:26.987654Z" if we have to output milliseconds and nanoseconds in the generated document, what should be the format string used in the tag? Is <<[node.C$CreatedAt1]:"yyyy-MM-dd HH mm ss SSS XXX">> this correct? Is this method used to register the date format pattern strings for the data in JSON payload or the desired output format strings mentioned in the tag of the template?
Therefore, we need to confirm: Which date format patterns are we expected to use with Aspose Words for Java? We believe the official documentation may require an update if .NET date formats are the intended standard, to prevent discrepancies and ensure clear guidance for Java developers.
There are two separate processes not related to each other: Outputting expression results and parsing of JSON strings. For the former, formats compatible with SimpleDateFormat should be used as per the documentation article. For the latter, formats that are passed using JsonDataLoadOptions.setExactDateTimeParseFormats should conform .NET custom format strings as per the reply.
Often, the answer is “no”, but in general, It depends.
By default (when JsonDataLoadOptions.setExactDateTimeParseFormats is not used), the engine tries a variety of formats (including ISO-based) as explained in remarks of the method. Sometimes, this may lead to unwanted parsing of strings as date-time values.
One of the purposes of JsonDataLoadOptions.setExactDateTimeParseFormats is to restrict parsing of date-time values to only specified formats. If such a restriction is not required according to your data, there is no need to use JsonDataLoadOptions.setExactDateTimeParseFormats to parse ISO-based date-time strings.
Since this format is used for outputting an expression result, it should conform SimpleDateFormat as explained in the beginning of this reply.
The format applied in a template in intended to be used for outputting an expression result as per the article, it has nothing to do with parsing of JSON strings.
date_test_files.zip (113.9 KB)
The attached date_test_files.zip also contains the template, JSON data, and full outcomes for your reference.
I’ve observed a couple of specific behaviors with setExactDateTimeParseFormats:
When null is passed to this method, dates are outputted using SimpleDateFormat. As SimpleDateFormat is limited to millisecond precision and does not support nanoseconds, what is the recommended approach for handling date output when sub-millisecond precision is required?
Conversely, when any other value is set for setExactDateTimeParseFormats, the date’s literal value is simply dumped into the output. Could you clarify if this is the intended behavior, or if I might be misunderstanding its usage?
All date-time formats supported for the current culture
All date-time formats supported for the English USA culture
All date-time formats supported for the English New Zealand culture
In some scenarios, you may need to disable recognition of date-time values at all, for example, when you deal with strings containing already formatted date-time values, which you do not want to re-format using the engine. You can achieve this by setting the exact date-time parse formats to an empty list.
From these quotes, it becomes clear that for nullList (which is the default value), several formats are checked and parsing works, whereas for emptyList, parsing is completely skipped.
For customList1, there is only one format: “yyyy-MM-ddTHH:mm:ss.FFFFFFFFFK”. According to the official reference, the maximum number of “F” specifiers is 7. When I change 9 F’s to 7 F’s, parsing also works.
For customList2, the list contains no format that conforms date-time strings in the JSON file, so parsing does not work either.
When a date-time string is not parsed as a date-time value, it is simply outputted as-is, no output formatting can be applied in this case.
As a note, usage of JsonDataLoadOptions.setExactDateTimeParseFormats overrides the default behavior. So, formats that are used for parsing by default are no longer applied. For more details, see Accessing JSON Data.
Thank you for your detailed, point-by-point response.
Regarding data handling in our multi-tenant SaaS service, we’ve identified several key considerations:
Data Ingestion: The data payload in requests is provided as JSON.
Tenant-Specific Formats: As a multi-tenant service, both the overall data formats and the displayed date formats in generated documents vary significantly from tenant to tenant, aligning with their specific domain models and business requirements.
setExactDateTimeParseFormats Behavior: While the JavaDocs suggest that strings in ExactDateTimeParseFormats are additional date-time formats utilizing the current culture, our testing indicates they override the default date formats. Given this behavior, attempting to set formats using setExactDateTimeParseFormats is impractical for a multi-tenant environment, as it cannot consistently meet the needs of all tenants and will likely result in incorrect date formatting for some templates.
Incorrect Date Parsing: We’ve observed instances where plain text data, such as “3-6” in a script tags, is incorrectly output as a date, even without explicit date format strings or the _Text suffix being applied.
Unsupported Date Formats: The engine currently does not handle several standard date formats, including: basic ISO date (YYYYMMDD), ISO date with timezone (e.g., Europe/Paris), ISO ordinal date (YYYY-DDD), ISO Week Date (YYYY-Wdd-D), and RFC 1123 Date.
Millisecond Truncation: The milliseconds part of a date is consistently displayed as “000” (e.g., “2000-12-25T15:27:21Z” formatted with “yyyy,MMM,dd HH:mm:ss.SSS” yields “2000, Dec, 25 15:27:21.000”).
Attached are the updated sample program, input file, and output documents for your reference. The table cells with incorrect outcomes are highlighted in color. date_issue_2.zip (149.1 KB)
Earlier in this post, the most of the questions have already been answered, so let us recap.
setExactDateTimeParseFormats Behavior: While the JavaDocs suggest that strings in ExactDateTimeParseFormats are additional date-time formats utilizing the current culture, our testing indicates they override the default date formats.
Javadoc suggests that it is an additional format to just one format (MS date-time format) rather than all formats applied by default. So, expectedly, all other default formats are not applied when using JsonDataLoadOptions.setExactDateTimeParseFormats as per my previous reply:
You can provide different sets of formats for different tenants. Alternatively, you can skip parsing of date-time strings at all (by passing an empty list to JsonDataLoadOptions.setExactDateTimeParseFormats) and process the strings as per your requirements including re-formatting by using a custom class as suggested in the previous reply:
This behavior is known and expected. The following quote from an earlier reply explains how to deal with this:
Most likely, it relates to parsing of simple-type JSON arrays. If so, then this is also expected and explained at Accessing JSON Data.
All formats applied by default are listed in Javadoc. Other formats are intended to be specified using JsonDataLoadOptions.setExactDateTimeParseFormats, so this can be tuned as per your requirements.
Maybe, there is some misunderstanding, but as far as I see, “2000-12-25T15:27:21Z” does not contain milliseconds, that is why, they are outputted as zeroes.
I checked the document generation test with millis “2000-12-25T15:27:21.123Z” formatted with “yyyy,MMM,dd HH:mm:ss.SSS”, again. For skip and null format list, it yields “2000, Dec, 25 15:27:21.123” and for empty it just dumps “2000-12-25T15:27:21.123Z” and custom format list, it yields “2000, Dec, 25 15:27:21.000”.
The dates are property values in the JSON payload; the service is not aware of which tenant is sending which data. The same tenant can send different date data for a template. So, it would be impossible to implement any tenant-specific logic and option configurations.
The properties like “actual”: “3-6” might not always be an array element. If “_Text” is only intended to represent an array element, then we lack ways to represent a value as plain text or as-is in simple scalar properties like this. And then the engine will misinterpret these as a date and time.
I am afraid the same applies to Aspose.Words LINQ Reporting Engine. You can only configure JsonDataLoadOptions.setExactDateTimeParseFormats, so this can be tuned as per your requirements.
Thank you for your reply and the answers to my queries. Since the built-in date formatting is not producing the desired results for all scenarios, we will proceed with using JsonDataLoadOptions.setExactDateTimeParseFormats to handle the known formats. While this approach will require ongoing updates as new date formats are requested by users, it appears to be the most viable solution, even though it does not offer a permanent, comprehensive fix.
