An empty array, a null object or a field that stopped arriving will stop a document assembling, even when the template guards against it. There are three ways to keep it running — a JSON Schema, AllowMissingMembers and InlineErrorMessages — and picking the wrong one hides a real problem instead of fixing it.

The report fills in perfectly on your machine. It runs for three weeks. Then one night it stops on the third customer of a batch of two thousand, and the message is about a member of a DataRow.

The data was valid. The template was correct. What went wrong is the gap between them — and there are three different ways to close it, each right for a different reason.

The runnable version of everything below is on GitHub — data-safe-templates-net.

The data that breaks a working template

{ "Name": "Quayside Bistro", "Account": "00042", "Cards": [], "Loyalty": null }

A customer who has not added a payment card yet and is not in the loyalty programme. Nothing is malformed. And a template that handles both cases properly —

<<if [customer.Cards.Count() > 0]>>Card: <<[customer.Cards.First().Type]>><<else>>No payment card on file.<</if>>

— still does not assemble:

An error has been encountered at the end of expression 'customer.Cards.First().Type]>'.
Can not get the value of member 'Type' on type 'System.Data.DataRow'.

The branch never renders. The engine still has to resolve the expression, and an empty array has no element type to resolve it against. The same reasoning turns "00042" into 42: with no other information, a string of digits is a number.

1. A JSON Schema, when the shape is known

New in 26.11 — schema support for JsonDataSource.

JsonDataSource dataSource = new JsonDataSource(
    "data/Customer.json",
    "data/Customer.schema.json");

new DocumentAssembler().AssembleDocument(
    "templates/Json schema.docx",
    "output/with-schema.docx",
    new DataSourceInfo(dataSource, "customer"));
{
  "type": "object",
  "properties": {
    "Name":    { "type": "string" },
    "Account": { "type": "string" },
    "Cards":   { "type": "array",
                 "items": { "type": "object", "properties": { "Type": { "type": "string" } } } },
    "Loyalty": { "type": ["object", "null"], "properties": { "Level": { "type": "string" } } }
  }
}

Now the element type of Cards is known whether or not any card is present, and Account is a string because the schema says so. Both failures disappear, and nothing about the template changed.

Use this when the data comes from a system whose contract you know: an API, an export, or a language model you prompted with the same schema.

2. AllowMissingMembers, when the data is genuinely sparse

A member that is not in the data at all. By default that is an error. With the option it renders as an empty value:

DocumentAssembler assembler = new DocumentAssembler
{
    Options = DocumentAssemblyOptions.AllowMissingMembers
};

This one deserves a moment of thought before you reach for it, because it is the easiest to misuse. It is right when a blank really is the correct output — an optional fax number, a middle name. It is wrong when a missing member means somebody renamed a field upstream and nobody noticed: with the option on, two thousand documents go out with a blank where the order total used to be, and nothing anywhere says so.

3. InlineErrorMessages, when the template is not yours

For templates edited by people outside your team. The error goes into the report, where the tag was, and AssembleDocument returns false:

DocumentAssembler assembler = new DocumentAssembler
{
    Options = DocumentAssemblyOptions.InlineErrorMessages
};

bool success = assembler.AssembleDocument(template, output, dataSourceInfo);

The batch finishes. The three documents that are wrong carry the reason in their own text, next to the tag that caused it, and you route those three to whoever owns the template instead of stopping the other 1,997.

Check the return value. A pile of documents with error text in them and nobody watching is worse than a crash.

Which one should you use?

Situation Use
The shape is known in advance; values may be empty, null or missing a JSON Schema
The data is genuinely sparse and a blank is correct AllowMissingMembers
Templates are edited outside your team InlineErrorMessages, and check the return value
A missing member means something upstream broke the default: let it throw

They combine. A schema plus InlineErrorMessages is a reasonable default for a service that assembles documents from data it does not own: the known shape is handled, and anything else is visible rather than silent.

Questions people ask

How do I handle missing data in a Word template in C#? Three ways, and they are not interchangeable: a JSON Schema when you know the shape in advance, DocumentAssemblyOptions.AllowMissingMembers when the data is genuinely sparse, and DocumentAssemblyOptions.InlineErrorMessages when the template is edited outside your team.

Why does an empty array break a template that guards it with <<if>>? The branch does not have to render for the expression to be resolved, and an empty array carries no element type to resolve .First().Type against. A JSON Schema supplies that type.

Why did my "00042" turn into 42? Without a schema the engine infers types from the data, and a string of digits is read as a number. Declaring "type": "string" keeps it.

Does AllowMissingMembers hide real problems? It can, and that is the main reason to think before switching it on. If a member disappears because somebody renamed a field upstream, the option turns that into blank space in every document and nothing reports it.

Does AssembleDocument tell me a document came out wrong? With InlineErrorMessages it returns false and puts the error into the document where the tag was. Check the return value — a pile of documents with error text and nobody watching is worse than an exception.

Try it

git clone https://github.com/groupdocs-assembly/data-safe-templates-net.git
cd data-safe-templates-net
dotnet run --project src/SafeTemplates -- all

It prints all four cases, including the two failures, so you can see exactly what each option changes.

The reference page is Templates for incomplete data.