nav-osa-types

Shared TypeScript definitions, XML parser, and XSD schemas for the Hungarian NAV Online Invoice System (OSA) version 3.0.

Contents

• TypeScript interfaces generated from the official NAV XSD schemas: common, invoiceBase, data, and invoiceApi
• Generic XML parser built on fast-xml-parser configured for NAV XML documents
• XSD validator using libxml2-wasm
• Helper to resolve XSD file paths at runtime

Installation

npm install nav-osa-types

Usage

Types

import { InvoiceData, TaxNumberType, MonetaryType } from 'nav-osa-types';

Parse XML

By default, parseXml validates the XML against the built-in NAV XSD schema before parsing. The schema is auto-detected from the root element:

import { parseXml, InvoiceData } from 'nav-osa-types';

const result = await parseXml<{ InvoiceData: InvoiceData }>(xmlString);

You can provide a custom XSD path or disable validation entirely:

// Custom XSD
const result = await parseXml(xmlString, { xsdPath: '/path/to/custom.xsd' });

// Disable validation (for trusted XML)
const result = await parseXml(xmlString, { validate: false });

If validation fails, a detailed XmlValidationError is thrown:

import { XmlValidationError } from 'nav-osa-types';

try {
  const result = await parseXml(xmlString);
} catch (err) {
  if (err instanceof XmlValidationError) {
    console.log('Validation failed:', err.errors);
  }
}

Validate XML

import { validateXml, getXsdPath, ValidationResult } from 'nav-osa-types';

const result: ValidationResult = await validateXml(xmlString, getXsdPath('data'));
if (!result.valid) {
  console.log('Errors:', result.errors);
}

XSD schemas

The module ships the official NAV XSD files:

• common.xsd — NTCA Common types
• invoiceBase.xsd — Base invoice types
• data.xsd — Invoice data types
• invoiceApi.xsd — API request/response types

Security options

The parser processes XML entities by default (processEntities: true) to protect against entity expansion attacks. For trusted XML (self-generated documents with no external input), you can disable this to reduce overhead:

const result = parseXml<InvoiceData>(xmlString, { processEntities: false });

Warning: Only disable entity processing when parsing XML you fully control. Never use this for external or untrusted input.

Payload size limit

The parser rejects XML payloads larger than 10 MB by default. You can override this:

const result = parseXml<InvoiceData>(xmlString, { maxXmlSize: 50 * 1024 * 1024 }); // 50 MB

License

Apache-2.0