XSD
Validate invoice XML against an XML Schema in-process.
The XSD plugin checks invoice XML against an XML Schema. Validation runs inside the current JavaScript runtime, with no Java runtime. A valid document resolves with no value. An invalid document throws ZugferdError.
Bundled schemas are embedded as source text, so validation also works in runtimes without a filesystem, such as Cloudflare Workers.
Installation
Install the plugin
npm install @node-zugferd/validator-xsd@betaAdd the plugin to your instance
Register the plugin in your zugferd instance. The package includes schemas for the Factur-X profiles.
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { xsd } from "@node-zugferd/validator-xsd";
export const invoicer = zugferd({
profiles: [en16931],
plugins: [
xsd(),
],
// ...
});Automatic validation
autoRun defaults to true. create then validates the XML it just built, and a schema failure rejects that call. An afterXMLBuild hook on your zugferd() options still runs after this check.
import { invoicer } from "./invoicer";
import { data } from "./data";
await invoicer.create("en-16931", data);With the parser plugin on the same instance, parse also runs XSD on the XML before it maps fields. Set autoRun: false to keep invoicer.xsd.validate available and skip both of those automatic checks.
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { parser } from "@node-zugferd/parser";
import { xsd } from "@node-zugferd/validator-xsd";
export const invoicer = zugferd({
profiles: [en16931],
plugins: [
parser(),
xsd({
autoRun: false,
}),
],
});Manual validation
invoicer.xsd.validate takes a profile id and the invoice XML as a string. The id may also be an object with an id field. Pass XML from disk, or the string returned by toXML().
import { readFile } from "node:fs/promises";
import { ZugferdError } from "@node-zugferd/core/error";
import { invoicer } from "./invoicer";
try {
await invoicer.xsd.validate(
"en-16931",
await readFile("factur-x.xml", "utf-8"),
);
} catch (error) {
if (error instanceof ZugferdError) {
console.error(error.message);
} else {
throw error;
}
}Supported profiles
These profiles ship with a schema:
validate throws when the profile id has no schema entry. With autoRun, create skips a profile that has no schema. parse calls validate, so a missing schema rejects the parse.
XRechnung and the Order-X profiles need a schemaMap entry.
Custom schemas
schemaMap is merged over the bundled Factur-X schemas. An entry you list replaces the bundled schema for that id.
An entry uses one of two forms:
pathand optionaldirread the root schema and its imports from disk. Use this in Node.js.contentand optionalimportskeep the schema in memory. Use this in runtimes without a filesystem, such as Cloudflare Workers.
import { xsd } from "@node-zugferd/validator-xsd";
xsd({
schemaMap: {
"en-16931": {
path: "./schemas/FACTUR-X_EN16931.xsd",
dir: "./schemas",
},
},
});path is the main XSD file. dir is the folder used to read imported schema files by name. The bundled Factur-X schemas use content and imports because each profile schema imports the data-type schemas next to it.
For a schema that imports other files, import each file as text with your bundler and pass the contents. The keys of imports are the schemaLocation values used by the root schema.
import invoiceXsd from "./schemas/invoice.xsd?raw";
import typesXsd from "./schemas/types.xsd?raw";
import { xsd } from "@node-zugferd/validator-xsd";
xsd({
schemaMap: {
invoice: {
content: invoiceXsd,
imports: {
"types.xsd": typesXsd,
},
},
},
});The XRechnung and Order-X schema definitions below already use content and imports.
XRechnung
npm install @node-zugferd/xrechnung-schema-definition@betaimport { zugferd } from "node-zugferd";
import { xsd } from "@node-zugferd/validator-xsd";
import { xrechnung } from "@node-zugferd/xrechnung";
import { xrechnungSchemaDefinitions } from "@node-zugferd/xrechnung-schema-definition";
export const invoicer = zugferd({
profiles: [xrechnung],
plugins: [
xsd({
schemaMap: xrechnungSchemaDefinitions,
}),
],
});Order-X
orderXSchemaDefinitions covers order-x-basic, order-x, and order-x-extended.
npm install @node-zugferd/order-x-schema-definition@betaimport { zugferd } from "node-zugferd";
import { orderX } from "@node-zugferd/order-x";
import { orderXSchemaDefinitions } from "@node-zugferd/order-x-schema-definition";
import { xsd } from "@node-zugferd/validator-xsd";
export const invoicer = zugferd({
profiles: [orderX],
plugins: [
xsd({
schemaMap: orderXSchemaDefinitions,
}),
],
});Findings
A schema violation throws ZugferdError. error.message is the message from the XSD validator.
A call to validate for a profile id with no schema throws ZugferdError with the message No XSD schema found for profile "<id>". Please provide a custom schema file name in the plugin options. Add a schemaMap entry for that id.
Compared to Mustang
XSD runs inside the Node.js process and needs no Java runtime. That makes it faster than Mustang, which starts a Java process for every check.
XSD checks the document against its XML Schema: which elements are present, how often they appear, and which types they use. Profile business rules are covered by Mustang.
Options
Prop
Type