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.
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:
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:
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:
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
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
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.