News

An invoice can have two readers. A person opens the PDF, checks the amount, and pays it. Or software extracts its data, so it can handle the invoice automatically. A regular PDF mostly serves the first reader and can make it difficult to trust automatic handling of invoices.

ZUGFeRD and Factur-X are standards used in Germany and France that solve this by putting both readers in one file: a normal PDF users can look at, with the structured invoice data embedded as XML for automation. This post explains why you would want or need that and how Oicana produces such a file from a Typst template.

More and more countries require invoices to carry machine-readable data, not just a printed layout. The relevant ones for the standards we are looking at here are:

• Germany mandates that businesses can receive structured e-invoices for domestic B2B since 2025, with required sending of e-invoices following in phases over the next years.
• France is rolling out a Factur-X based mandate on a similar timeline.

Even where it is not yet required, structured invoices save work. The recipient’s system reads the totals, tax rates, and line items straight from the file. No manual entry, no OCR guesswork, fewer mistakes.

Three things have to line up for a valid e-invoice:

1. A PDF/A-3 document (the archivable, self-contained PDF profile).
2. The invoice XML embedded as an associated file.
3. XMP metadata in the PDF that declares the embedded XML and which profile it follows.

Get one of those wrong and validators can reject the file. This makes e-invoices fiddly to produce by hand.

Oicana compiles a Typst template to PDF, and its PDF export can embed files and write custom XMP metadata. That is exactly what the three points above need.

The invoice_zugferd example template shows the full setup.

1. Export to PDF/A-3 in the manifest. You declare the standards once, next to the template:

[tool.oicana.export.pdf]
standards = ["ua-1", "a-3b"]

[[tool.oicana.inputs]]
type = "blob"
key = "zugferd"
default = { file = "factur-x.xml" }

Here the invoice XML comes in as a blob input, so you can pass a different one per invoice. The a-3b standard allows embedding files to be a valid e-invoice. Adding ua-1 makes the same document more accessible through PDF/UA-1.

2. Embed the XML in the template. A single line takes the XML bytes, embeds them, and writes the matching XMP metadata:

#import "@preview/oicana:0.2.0": setup
#import "@local/invoice-harness:0.1.1": *

#let read-project-file(path) = read(path, encoding: none)
#let (input, oicana-image, _) = setup(read-project-file)

// Embed the invoice XML and declare it in the PDF metadata
#factur-x(input.zugferd.bytes, profiles.en16931)

// ... the rest of the template renders the visible invoice

The factur-x call handles the embedding and the XMP. The rest of the template is an ordinary invoice layout, free to look however you want.

The Oicana documentation includes a guide on creating e-invoices with one of our seven integrations. You can follow it see how to generate e-invoices from Node.js, the browser, Python, Rust, Java, PHP, or C#.

With Oicana it’s easy to create e-invoices in your code.

Accessibility reaches a lot further than websites. It includes the PDFs you generate for your customers. Invoices, statements, contracts, tickets, and reports are part of the service you offer, and services have to be accessible.

This post looks at what the European Accessibility Act and the US accessibility framework (ADA and Section 508) mean for businesses that produce PDFs, whether PDF/UA is actually required, and how Oicana exports PDF/UA-1 documents from Typst templates.

The European Accessibility Act (Directive (EU) 2019/882) became enforceable on 28 June 2025. It requires a broad set of products and services sold in the EU to be accessible to people with disabilities. It includes services like e-commerce, consumer banking, e-books, transport, or telecoms and applies regardless of where your company is based. If you sell into the EU market, you are in scope. Any customer facing PDFs that you generate are part of your service and need to be accessible.

Two important nuances:

• Microenterprise exemption (services): organizations with fewer than 10 employees and annual turnover below €2 million are generally exempt for the services parts of the EAA.
• A transition window: new products and services have to comply from 28 June 2025. Many existing ones have until 28 June 2030.

Penalties are set by each member state and can be severe. There can be fines, and in some jurisdictions removal of a product or service from the market.

The EAA itself contains no checklist. It points at the harmonized European standard EN 301 549, which in turn incorporates the Web Content Accessibility Guidelines (WCAG) 2.1 Level AA as the technical benchmark for digital content. So in practice, “accessible” means “meets WCAG 2.1 AA”. That applies to document content and to web pages.

• Section 508 of the Rehabilitation Act applies to US federal agencies and the vendors that sell to them. Its refresh adopted WCAG 2.0 Level AA as the technical baseline for electronic content, including PDF documents, and the standard is widely paired with PDF/UA to make PDFs conform.
• The Americans with Disabilities Act (ADA) applies to private “places of public accommodation”. The Department of Justice has stated that the ADA’s requirements extend to the goods and services businesses offer on the web, pointing to WCAG as helpful guidance. In its 2024 Title II rule DOJ went further and formally adopted WCAG 2.1 AA (including for documents) for state and local governments.

Across both continents: WCAG is the legal benchmark and a PDF has to carry the structure a screen reader needs in order to satisfy it.

Short answer: not literally, but it is the recognized way to get there for PDFs.

PDF/UA (“Universal Accessibility”, ISO 14289) is the technical standard that defines how an accessible PDF must be built: a complete tag tree, a logical reading order, alternative text for images and formulas, a declared document language and title, and so on. The law mandates the outcome (WCAG conformance), and PDF/UA is the established, testable specification for achieving that outcome in the PDF format.

In other words:

The EAA / EN 301 549 do not name PDF/UA as mandatory. They require WCAG 2.1 AA. PDF/UA is how the PDF industry implements those requirements. A PDF/UA-conformant file carries exactly the tagging, metadata, and structure that WCAG asks for. Pairing PDF/UA conformance with WCAG is widely seen as the safest, most future-proof approach for any organization producing PDFs at scale.

So if you generate PDFs and want a clear, verifiable target, “produce PDF/UA” is the practical goal.

A handful of brochures can be remediated by hand in Acrobat. But the documents that put a business in scope are usually the generated ones: thousands of invoices a day, per-customer statements, contracts assembled from data. You cannot manually tag those after the fact. Accessibility has to be produced at generation time, by the template and the engine, consistently, on every document.

This is where a lot of PDF tooling struggles. Headless-browser HTML-to-PDF pipelines produce weak or no tag trees; many imperative PDF libraries leave tagging entirely to you. Getting reliable, valid tags out of them is a project in itself.

Oicana compiles Typst templates to PDF, and Typst’s PDF export was built with accessibility in mind. Two things matter here:

1. Tagged PDFs by default. Oicana produces tagged (accessible) PDFs out of the box. The tag tree is the foundation everything else builds on. The semantic markup you already write in Typst (= Heading, lists, figure, tables) maps to the corresponding PDF structure elements automatically, so a well-structured template yields a well-structured document.

2. One-line PDF/UA-1 export. You opt into PDF/UA-1 directly in the template manifest:

[tool.oicana.export.pdf]
standards = ["ua-1"]

That is all the integration code needs to know. The same Typst template exports a PDF/UA-1 file whether you compile it from Node.js, Python, Java, Rust, C#, PHP, or the browser. (Oicana’s default standard is PDF/A-3b; PDF/A profiles such as a-2a/a-3a are also tagged and accessibility-oriented if you need PDF/A instead.)

PDF/UA is a contract, and Typst holds you to it. Producing a valid PDF/UA-1 file requires real accessibility metadata in the template, and if something is missing, the compile fails with a clear error rather than silently shipping a broken file. At minimum you need:

• a document title and a document language,
• alternative text on every image and formula,
• genuine semantic structure (headings, lists, tables) instead of visual fakes,
• decorative elements marked as artifacts so screen readers skip them.

In an Oicana template that looks like this:

#import "@preview/oicana:0.2.0": setup

#let read-project-file(path) = read(path, encoding: none)
#let (input, oicana-image, _) = setup(read-project-file)

// Required for PDF/UA-1: a title and a language
#set document(title: "Invoice " + input.invoice.number)
#set text(lang: "en")

= Invoice #input.invoice.number

// Images need alternative text
#figure(
  oicana-image("logo", alt: "Acme Corporation logo"),
)

Billed to #input.invoice.customer

• Accessibility lives in the template, not scattered across application code. Flip one manifest setting and every document your service emits is PDF/UA-1, across all integrations and tech stacks.
• Templates are plain text in version control. Accessibility requirements, alt-text conventions, and the standard you target are reviewable and diffable like any other code.
• Failures are loud. A missing title or alt text breaks the build, so a regression cannot quietly ship a non-conformant invoice to a customer.
• Built on open source. Typst’s compiler and its PDF export are open source, so your accessible-document pipeline isn’t locked to a single vendor.

If accessibility is on your roadmap, generating PDF/UA documents from data is one of the trickier pieces to get right. Oicana makes it a manifest setting on top of a templating system you can read, review, version, and use from many different tech stacks.

Generating PDFs from application code is usually a pick-your-poison choice. HTML-to-PDF tools have fragile pagination and weak typography, PDF libraries put verbose layout code into your application, and SaaS PDF builders often come with proprietary template formats and vendor lock-in.

Oicana takes a different route. Templates are plain Typst projects. Your application passes typed inputs (JSON, images), and Oicana compiles a PDF.

• Multi-platform: the same template works across all integrations: browser, Node.js, C#, Java, Rust, Python, and PHP.
• Powerful layouting: templates use the full power of Typst, including its package ecosystem.
• Performant: PDFs can generate in single digit milliseconds with warmed-up templates in native integrations.
• AI and version control ready: templates are text files. They live next to your code, and AI can help write them.
• Minimal vendor lock-in: templates are plain Typst projects. The Typst compiler is open source.

Here’s a minimal Oicana template, a single Typst file with a manifest defining one JSON input:

#import "@preview/oicana:0.2.0": setup

#let read-project-file(path) = read(path, encoding: none)
#let (input, oicana-image, oicana-config) = setup(read-project-file)

#set document(date: datetime.today())

= Hello from Oicana, #input.info.name

[package]
name = "example"
version = "0.1.0"
entrypoint = "main.typ"

[tool.oicana]
manifest_version = 1

[[tool.oicana.inputs]]
type = "json"
key = "info"

Typst is a modern markup-based typesetting system. In main.typ, the = marks a heading and # switches to code mode. The first line imports the Typst Oicana package and the next two lines set it up. In the last line is the actual visual content of our document. #input.info.name interpolates the name field of the info input into the document.

In typst.toml, we define metadata for the template like a name, entrypoint, and inputs. The example defines a single input of type json (see the Oicana documentation on inputs). If the input value is { "name": "Alice" }, the content of our document will be a header reading “Hello from Oicana, Alice”.

There are good options for working on Typst documents like the official webapp and several IDE plugins. this is what it can look like to work on an Oicana template in VS Code using the Tinymist Typst extension with syntax highlighting and live preview:

You can find an open source collection of example Oicana templates on GitHub, including the certificate template shown above.

If you install the Oicana CLI and run oicana pack in the template directory, it produces the file example-0.1.0.zip that any Oicana integration can compile. Passing { "name": "Alice" } for the info input from your application looks like this in the different integrations (omitting some general boilerplate):

import { Template } from '@oicana/browser';

const templateFile = await fetch('/example-0.1.0.zip');
const template = new Template(new Uint8Array(await templateFile.arrayBuffer()));

const jsonInputs = new Map<string, string>();
jsonInputs.set('info', JSON.stringify({ name: 'Alice' }));

const pdf = template.compile(jsonInputs, new Map());

using System.Text.Json.Nodes;
using Oicana;
using Oicana.Config;
using Oicana.Inputs;

var template = new Template(File.ReadAllBytes("example-0.1.0.zip"));

var jsonInputs = new Dictionary<string, JsonNode>
{
    ["info"] = JsonNode.Parse("""{ "name": "Alice" }""")!,
};

var pdf = template.Compile(
    jsonInputs,
    new Dictionary<string, BlobInput>(),
    ExportFormat.Pdf(),
    new CompilationOptions(CompilationMode.Production));

import com.oicana.Template;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Map;

byte[] templateBytes = Files.readAllBytes(Path.of("example-0.1.0.zip"));
try (var template = new Template(templateBytes)) {
    byte[] pdf = template.compile(Map.of("info", "{\"name\":\"Alice\"}"), Map.of());
}

import { readFile } from 'node:fs/promises';
import { Template } from '@oicana/node';

const template = new Template(await readFile('example-0.1.0.zip'));

const jsonInputs = new Map<string, string>();
jsonInputs.set('info', JSON.stringify({ name: 'Alice' }));

const pdf = template.compile(jsonInputs, new Map());

use std::fs::File;

use oicana::Template;
use oicana_input::TemplateInputs;
use oicana_input::input::json::JsonInput;

let mut template = Template::init(File::open("example-0.1.0.zip")?)?;

let mut inputs = TemplateInputs::new();
inputs.with_input(JsonInput::new(
    "info",
    serde_json::json!({ "name": "Alice" }).to_string(),
));

let pdf = template.compile(inputs)?;

import json
from pathlib import Path

from oicana import Template

template_bytes = Path("example-0.1.0.zip").read_bytes()

with Template(template_bytes) as template:
    pdf = template.compile(
        json_inputs={"info": json.dumps({"name": "Alice"})},
    )

use Oicana\Template;

$template = new Template(file_get_contents('example-0.1.0.zip'));

try {
    $pdf = $template->compile(
        jsonInputs: ['info' => ['name' => 'Alice']],
    );
} finally {
    $template->cleanup();
}

One template, seven tech stacks including the browser. The getting started guide walks through this end-to-end for your stack of choice.

Non-commercial use is free: Personal projects, hobby use, research, education, and use by charitable organizations, educational institutions, public research organizations, and government institutions are covered by the PolyForm Noncommercial License.

Commercial licenses are available on the homepage. Licenses are per application, priced by company size, and every subscription includes the CLI and all integrations. All prices include VAT.

• Startup: €19/month, for companies up to €2M yearly revenue
• Scaleup: €49/month, for companies up to €25M yearly revenue
• Enterprise: €99/month, for companies above €25M yearly revenue

Annual billing saves 15%. Every subscription comes with a 30-day money-back guarantee. If Oicana doesn’t fit, email support@oicana.com for a refund.

Oicana was already used in production during the alpha and improved based on the learnings. The same idea goes for the beta. If something feels off, please let us know. That’s the feedback that shapes the road from beta to 1.0.

Give Oicana a try and get started with the setup guide.

It’s been a busy few months for Oicana. Here’s what’s new.

We’ve added two new integrations to the lineup: Java and PHP. Together with the existing browser, C#, Node.js, Rust, and Python integrations, Oicana now covers most of the major server-side ecosystems. Check out the getting started documentation to try it out.

Just like the other integrations, the two new ones come with open source example applications. A small Spring Boot Java application and a php service using Slim demonstrate backend services that can generate PDFs from templates and data with Oicana.

The docs have been migrated from Typst to MDX and included in this website. While we love Typst and still plan to eventually use it for the website and the online documentation, there were too many small issues in making the documentation look good in a responsive website. The Typst version of the documentation will at some point power the online documentation again.

Oicana is approaching beta. For the moment, no new integrations are planned, to focus on improving what we already have. The non-commercial license will stay and pricing for commercial licenses is work in progress. More details on that soon — stay tuned.