Handle Missing and Null Data in Templates

View as MarkdownMarkdown

Set up your AI agent

Give your coding agent live access to the GroupDocs documentation and API reference through the GroupDocs Docs MCP server — no install, no API key. Learn more

claude mcp add --transport http groupdocs-docs https://docs.groupdocs.com/mcp

Also process documents locally

The GroupDocs.Assembly MCP server lets your agent work with files on your machine; they are never uploaded. It needs the .NET 10 SDK or Docker.

claude mcp add groupdocs-assembly -- dnx GroupDocs.Assembly.Mcp --yes
Folders, licensing and more →

Data has holes: a customer with no payment card yet, a loyalty record that is null, a field an upstream system quietly stopped sending. A report that fills in perfectly during development and fails on the third customer of the night batch is the usual way this is discovered.

Three mechanisms decide what happens instead. Pick by what a hole means in your case.

Note
A runnable implementation of this page is on GitHub: data-safe-templates-net.

The data this page uses

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

Valid JSON, and a correct template over it still does not assemble.

1. A JSON Schema: the shape is known in advance

Note
Schema support for JsonDataSource is available since version 26.11.

Without a schema the engine learns the shape of the data from the data itself, which fails in two ways:

  • an empty array gives it no element type, so <<[customer.Cards.First().Type]>> cannot be resolved — even though the branch around that tag is never rendered;
  • "00042" looks like a number, so it is loaded as 42 and the document shows the wrong account.

Passing the schema settles both before the first value is read:

JsonDataSource dataSource = new JsonDataSource(
    Path.Combine(DataSourcesPath, "Customer.json"),
    Path.Combine(DataSourcesPath, "Customer.schema.json"));

DocumentAssembler assembler = new DocumentAssembler();
assembler.AssembleDocument(
    Path.Combine(TemplatesPath, "Json schema.docx"),
    Path.Combine(OutputPath, "with-schema.docx"),
    new DataSourceInfo(dataSource, "customer"));

Members the schema declares may be used by the template even when the data has them empty, null or missing, and their types come from the schema:

{
  "$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" } } }
  }
}

Use this when the data comes from a system whose contract you know — an API, an export, the output of a model you prompted with the same schema. Details are on Working with JSON data sources.

2. AllowMissingMembers: the data is genuinely sparse

A member the data does not have at all. By default that is an error:

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

With the option it renders as an empty value and the document is produced:

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

assembler.AssembleDocument(template, output, new DataSourceInfo(data, "customer"));

Use it when a blank really is the right output. Leave it off when a missing member means somebody changed the data and nobody noticed — that is the case where you want the batch to stop.

3. InlineErrorMessages: the template is not yours

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

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

bool success = assembler.AssembleDocument(template, output, new DataSourceInfo(data, "customer"));

A nightly batch of two thousand documents finishes, and the three that are wrong carry the reason in their own text, next to the tag that caused it. Check the return value and route those three to whoever owns the template — see Error handling.

Choosing

SituationUse
The shape is known in advance; values may be empty, null or missinga JSON Schema
The data is genuinely sparse and a blank is correctAllowMissingMembers
Templates are edited outside your teamInlineErrorMessages, and check the return value
A missing member means something upstream brokethe default: let it throw

The options combine. A schema plus InlineErrorMessages is a reasonable default for a service that assembles documents from data it does not own.

Frequently asked questions

How do you handle missing data in a document template in C#? With a JSON Schema when the shape is known 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 already guards it with <<if>>? The expression is resolved whether or not the branch renders, and an empty array carries no element type to resolve a member against. A schema supplies that type.

Why is a string of digits such as "00042" turned into a number? Type inference from the data. Declare the member as "type": "string" in the schema.

Does AllowMissingMembers hide genuine problems? It can. If a member disappears because a field was renamed upstream, the option renders blanks in every document and nothing reports it. Prefer a schema when the shape is known.

How do you know a document assembled with errors? AssembleDocument returns false when InlineErrorMessages is set, and the error text is placed in the document where the tag was.