node-zugferd
IntroductionInstallation

General

ParserTemplates

Exchange Networks

TRAFFIQX®

Validators

MustangXSD

Utilities

Magic BytesInstrumentation

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@beta

Add the plugin to your instance

Register the plugin in your zugferd instance. The package includes schemas for the Factur-X profiles.

invoicer.ts
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.

invoice.ts
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.

invoicer.ts
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().

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

  • Minimum
  • Basic WL
  • Basic
  • EN 16931
  • Extended

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:

  • path and optional dir read the root schema and its imports from disk. Use this in Node.js.
  • content and optional imports keep the schema in memory. Use this in runtimes without a filesystem, such as Cloudflare Workers.
invoicer.ts
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.

invoicer.ts
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@beta
invoicer.ts
import { 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@beta
invoicer.ts
import { 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


 

llms.txt
Mustang

Validate invoice XML with the Mustang CLI.

Magic Bytes

Check binary attachments against file signatures before an invoice is created.

Edit on GitHubPrivacyImprint

On this page

InstallationInstall the pluginAdd the plugin to your instanceAutomatic validationManual validationSupported profilesCustom schemasXRechnungOrder-XFindingsCompared to MustangOptions

How is this guide?