---
title: "API"
description: "The packages, the template class with Inspect, Validate and Render, the render settings and result, and flat documents."
audience: "Developers"
kind: "Reference"
status: "Current"
version: "main · 3.3 (unreleased)"
slug: "api"
url: "https://docs.allors.com/documents/api/"
---

# API

> **Status: Current.** Reference for developers.

This page is the reference for the public API: the two packages, the template class and its three operations, the settings a render takes, what a render returns, and the two forms of a document. The namespaces are `Allors.Document.OpenDocument` for the template, the settings and the result, `Allors.Document.Validation` for findings and validation, `Allors.Document.Inspection` for inspection, `Allors.Document.Models` for the model contracts and the formatting, and `Allors.Document.Reflection` for the reflection package.

<a id="packages"></a>

## Packages

| Package | Holds |
| --- | --- |
| `Allors.Documents` | The template and its renderer, the tag language, `Inspect`, `Validate`, the model contracts (`IShape`, `IResolver`) and the dictionary shape and resolver. Targets netstandard2.0 and net10.0, is trimmable and AOT-compatible, uses no reflection and has no dependencies. |
| `Allors.Documents.Reflection` | `OpenDocumentTemplate<T>`, `ReflectionShape` and `ReflectionResolver`: templates over plain classes and dictionaries, their members read through reflection. |

<a id="template"></a>

## Template

`OpenDocumentTemplate` reads a template from its bytes and keeps it ready to render; `Render` is its instance operation, `Inspect` and `Validate` are static and take the bytes. A template over a model type sees the public properties of `T` by their exact names and reads what is below them through reflection. The non-generic `OpenDocumentTemplate` takes any model and reads it as a dictionary unless the settings name another resolver:

```csharp
var template = new OpenDocumentTemplate(templateBytes);
var model = new Dictionary<string, object> { ["Invoice"] = invoice, ["Issuer"] = issuer };
var settings = new RenderSettings { Resolver = ReflectionResolver.Instance, Culture = new CultureInfo("nl-BE"), DateCulture = CultureInfo.InvariantCulture, Number = "N2", Date = "dd-MMM-yyyy" };
RenderResult result = template.Render(model, settings);
```

A template is read once and rendered any number of times, from any thread. It may be a package (`.odt`) or a flat document (`.fodt`), and it renders a package unless the settings ask for a flat document. Reading a template throws `InvalidDataException` when the bytes are not an OpenDocument text, and `TemplateException` when a block never ends, an end opens nothing, an else belongs to no condition or a block would cut a table; `Findings` says which tags and where. A render never throws for what the template says: a value the model cannot give prints blank, and `Findings` reports it.

`OpenDocumentTemplate<T>`, in `Allors.Documents.Reflection`, adds a typed `Render(T model, RenderSettings settings = null)`; `ReflectionShape.Arguments<T>()` is the shape that matches it for `Validate`. [Render your first document](https://docs.allors.com/documents/render-your-first-document.md) walks through both.

<a id="render-settings"></a>

## Render settings

`RenderSettings` carries how a render reads and formats its model: the resolver that binds paths to values, the caller’s formatting defaults and the output form. The template’s own document settings win over these, and a tag’s attributes win over both; a layer’s culture resets the number and date cultures of the layers below it. [Formatting](https://docs.allors.com/documents/formatting.md) has the rules.

| Member | Meaning |
| --- | --- |
| `Resolver` | Binds paths to the model’s members; the template’s own resolver when null: `DictionaryResolver`, or the reflection resolver of a template over a model type. |
| `Culture` | The culture values print in and text sorts by; the invariant culture when null. |
| `NumberCulture` | The culture numbers print in when it is not `Culture`; null when they print in the culture. |
| `DateCulture` | The culture dates, times and date-times print in when it is not `Culture`; null when they print in the culture. |
| `Date`, `Time`, `DateTime`, `Number` | The patterns for a date without a time, a time without a date, a date with a time and a number; the culture’s default when null. |
| `True`, `False` | The words a true and a false value print; `true` and `false` when null. |
| `Flat` | True to render a flat document (`.fodt`), one XML file with the pictures embedded; false, the default, renders a package (`.odt`). Either way the template may be a package or a flat document. |

<a id="render-result"></a>

## Render result

`RenderResult` holds `Document`, the rendered document, and `Findings`: every member the template asked for that the model does not have, every loop that could not be ordered and every tag that could not be read, each once, in document order, and empty when the template and the model agree. The document is complete either way: a missing value prints blank, an unordered loop keeps the collection’s order and an unreadable tag prints as typed.

A `Finding` has its `Kind` and `Severity`, the `Text` of the tag, frame name or setting as the author typed it, the `Path` that was checked when the finding is about one, a `Message` and a `Location`. A `Location` names the `Part` (`content.xml` or `styles.xml`), the `Paragraph` as a 1-based ordinal in the part, 0 outside any paragraph, and the `ParagraphText` with the tags as typed, white space collapsed, at most 200 characters. [Findings](https://docs.allors.com/documents/findings.md) lists the kinds.

<a id="inspect"></a>

## Inspect

`Inspect` reads a template without a model and lists what it asks for: every tag in document order with its part and paragraph, the bound picture frames, the maps, the document settings, and the tags it cannot read.

```csharp
TemplateInspection inspection = OpenDocumentTemplate.Inspect(templateBytes);


inspection.Paths;      // every distinct path, bindings and pictures alike
inspection.Bindings;   // the <$path> tags, each with Tag, Location and the enclosing Block
inspection.Blocks;     // the for, if and ifdef tags, each with its Children, Elses and End
inspection.Pictures;   // the frames whose description is a picture tag, each with FrameName, Tag and Location
inspection.Maps;       // the map tables, each with Name, Entries, Default and Location
inspection.Settings;   // the custom document properties
inspection.Problems;   // malformed tags, unbalanced blocks, elses without a condition and maps that cannot be read
```

A `Location` names the part (`content.xml` or `styles.xml`), the paragraph’s ordinal and its text.

<a id="validate"></a>

## Validate

`Validate(byte[] document, IShape root)` checks a template against the shape of its model without rendering it and returns a `TemplateValidation`: its `Findings` in document order, `content.xml`, then `styles.xml`, then the document settings; `IsValid`, true when there is no error; and the `Inspection` the findings came from. [Validate templates](https://docs.allors.com/documents/validate-templates.md) says which shape to pass and how a condition narrows what its branches see.

<a id="flat-documents"></a>

## Flat documents

A template may be a flat OpenDocument text (`.fodt`, File, Save As, Flat XML ODF Text Document): one XML file with the pictures embedded. `RenderSettings.Flat = true` renders one, pictures embedded as base64; the default is a package, whatever the template’s form. The findings of a flat template name `content.xml` for the body and `styles.xml` for the styles with the headers and footers, the parts the engine splits it into. Embedded objects such as charts and formulas are not converted between the two forms.