@stackforge-eu/factur-x 1.0.8 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-05-27
+
+- **BREAKING:** Every `ram:GlobalID` and the legal-organization `ram:ID` now
+  carry the `@schemeID` attribute required by EN 16931. The XSD-canonical CII
+  mapping makes the scheme mandatory on `ram:GlobalID` (BT-29-1 / BT-46-1 for
+  parties, BT-157-1 for line items) and conditional on
+  `ram:SpecifiedLegalOrganization/ram:ID` (BT-30-1 / BT-47-1); without these
+  attributes Mustang / KoSIT / veraPDF's Factur-X profile reject the invoice
+  even though the embedded CII looked superficially correct. Three input
+  fields changed:
+  - `TradePartyInput.globalId` is now `IdentifierWithSchemeInput`
+    (`{ value: string; schemeID: string }`) instead of a bare `string`
+  - `InvoiceLineInput.standardIdentifier` is now `IdentifierWithSchemeInput`
+    instead of a bare `string` (sibling fix on top of #4 — the line-item
+    `ram:GlobalID` had the same defect as the party one)
+  - `LegalOrganizationInput.schemeID?: string` added (optional, mirrors the
+    conditional spec rule)
+  Migration: `globalId: "4000001000005"` →
+  `globalId: { value: "4000001000005", schemeID: "0088" }` (and the analogous
+  rewrite for `standardIdentifier`). The new `IdentifierWithSchemeInput` type
+  is exported from `src/index.ts`. Regression test added in
+  `tests/xsd-validator.test.ts` that drives all three schemed identifiers
+  through the EN16931 XSD in one go (thanks @sco-indy, #4).
+
 ## [1.0.8] — 2026-05-27
 
 - **PDF trailer was missing the `/ID` entry required by PDF/A-3.** ISO 19005-3
@@ -129,6 +153,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Deno compatibility test suite
 
 [Unreleased]: https://github.com/StackForge-EU/factur-x/commits/main
+[1.1.0]: https://github.com/StackForge-EU/factur-x/compare/v1.0.8...v1.1.0
 [1.0.8]: https://github.com/StackForge-EU/factur-x/compare/v1.0.7...v1.0.8
 [1.0.7]: https://github.com/StackForge-EU/factur-x/compare/v1.0.6...v1.0.7
 [1.0.6]: https://github.com/StackForge-EU/factur-x/compare/v1.0.5...v1.0.6

package/dist/index.cjs

@@ -340,13 +340,21 @@ function buildParty(p, profile) {
     const ids = Array.isArray(p.id) ? p.id : [p.id];
     for (const id of ids) x += tag("ram:ID", escapeXml(id));
   }
-  if (p.globalId) x += tag("ram:GlobalID", escapeXml(p.globalId));
+  if (p.globalId) {
+    x += tag("ram:GlobalID", escapeXml(p.globalId.value), { schemeID: p.globalId.schemeID });
+  }
   x += tag("ram:Name", escapeXml(p.name));
   if (p.description && atLeast(profile, "EN16931" /* EN16931 */))
     x += tag("ram:Description", escapeXml(p.description));
   if (p.legalOrganization) {
     let lo = "";
-    if (p.legalOrganization.id) lo += tag("ram:ID", escapeXml(p.legalOrganization.id));
+    if (p.legalOrganization.id) {
+      lo += tag(
+        "ram:ID",
+        escapeXml(p.legalOrganization.id),
+        p.legalOrganization.schemeID ? { schemeID: p.legalOrganization.schemeID } : void 0
+      );
+    }
     if (p.legalOrganization.tradingName)
       lo += tag("ram:TradingBusinessName", escapeXml(p.legalOrganization.tradingName));
     x += tag("ram:SpecifiedLegalOrganization", lo);
@@ -374,7 +382,11 @@ function buildLineItem(line, profile) {
   let doc = tag("ram:LineID", escapeXml(line.id));
   if (line.note) doc += tag("ram:IncludedNote", tag("ram:Content", escapeXml(line.note)));
   let prod = "";
-  if (line.standardIdentifier) prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier));
+  if (line.standardIdentifier) {
+    prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier.value), {
+      schemeID: line.standardIdentifier.schemeID
+    });
+  }
   if (line.sellerAssignedId) prod += tag("ram:SellerAssignedID", escapeXml(line.sellerAssignedId));
   if (line.buyerAssignedId) prod += tag("ram:BuyerAssignedID", escapeXml(line.buyerAssignedId));
   prod += tag("ram:Name", escapeXml(line.name));

package/dist/index.d.cts

@@ -448,9 +448,18 @@ interface TaxRegistrationInput {
 interface LegalOrganizationInput {
     /** Registration identifier */
     id?: string;
+    /** Registration identifier scheme (ICD code list value, e.g. `"0002"` for SIRENE) */
+    schemeID?: string;
     /** Trading business name */
     tradingName?: string;
 }
+/**
+ * Identifier value with its scheme identifier.
+ */
+interface IdentifierWithSchemeInput {
+    value: string;
+    schemeID: string;
+}
 /**
  * Trade party (seller, buyer, payee, etc.).
  *
@@ -468,10 +477,14 @@ interface TradePartyInput {
      */
     id?: string | string[];
     /**
-     * Global identifier with scheme (e.g. GLN `"0088:1234567890123"`).
+     * Global identifier with scheme (e.g. GLN value `"4000001000005"` and
+     * ICD scheme `"0088"`).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID`.
+     *
      * @see EN 16931 BT-29-1 / BT-46-1
      */
-    globalId?: string;
+    globalId?: IdentifierWithSchemeInput;
     /** Postal address — mandatory for BASIC_WL and above */
     address?: AddressInput;
     /**
@@ -581,10 +594,14 @@ interface InvoiceLineInput {
      */
     description?: string;
     /**
-     * Item standard identifier (e.g. GTIN/EAN).
+     * Item standard identifier (e.g. GTIN value `"4012345678901"` and ICD
+     * scheme `"0160"` for GS1).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID` (BT-157-1).
+     *
      * @see EN 16931 BT-157
      */
-    standardIdentifier?: string;
+    standardIdentifier?: IdentifierWithSchemeInput;
     /**
      * Seller-assigned item identifier.
      * @see EN 16931 BT-155
@@ -1435,4 +1452,4 @@ interface XRechnungResult {
  */
 declare function toXRechnung(input: FacturXInvoiceInput, options?: XRechnungOptions): XRechnungResult;
 
-export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };
+export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type IdentifierWithSchemeInput, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };

package/dist/index.d.ts

@@ -448,9 +448,18 @@ interface TaxRegistrationInput {
 interface LegalOrganizationInput {
     /** Registration identifier */
     id?: string;
+    /** Registration identifier scheme (ICD code list value, e.g. `"0002"` for SIRENE) */
+    schemeID?: string;
     /** Trading business name */
     tradingName?: string;
 }
+/**
+ * Identifier value with its scheme identifier.
+ */
+interface IdentifierWithSchemeInput {
+    value: string;
+    schemeID: string;
+}
 /**
  * Trade party (seller, buyer, payee, etc.).
  *
@@ -468,10 +477,14 @@ interface TradePartyInput {
      */
     id?: string | string[];
     /**
-     * Global identifier with scheme (e.g. GLN `"0088:1234567890123"`).
+     * Global identifier with scheme (e.g. GLN value `"4000001000005"` and
+     * ICD scheme `"0088"`).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID`.
+     *
      * @see EN 16931 BT-29-1 / BT-46-1
      */
-    globalId?: string;
+    globalId?: IdentifierWithSchemeInput;
     /** Postal address — mandatory for BASIC_WL and above */
     address?: AddressInput;
     /**
@@ -581,10 +594,14 @@ interface InvoiceLineInput {
      */
     description?: string;
     /**
-     * Item standard identifier (e.g. GTIN/EAN).
+     * Item standard identifier (e.g. GTIN value `"4012345678901"` and ICD
+     * scheme `"0160"` for GS1).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID` (BT-157-1).
+     *
      * @see EN 16931 BT-157
      */
-    standardIdentifier?: string;
+    standardIdentifier?: IdentifierWithSchemeInput;
     /**
      * Seller-assigned item identifier.
      * @see EN 16931 BT-155
@@ -1435,4 +1452,4 @@ interface XRechnungResult {
  */
 declare function toXRechnung(input: FacturXInvoiceInput, options?: XRechnungOptions): XRechnungResult;
 
-export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };
+export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type IdentifierWithSchemeInput, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };

package/dist/index.js

@@ -310,13 +310,21 @@ function buildParty(p, profile) {
     const ids = Array.isArray(p.id) ? p.id : [p.id];
     for (const id of ids) x += tag("ram:ID", escapeXml(id));
   }
-  if (p.globalId) x += tag("ram:GlobalID", escapeXml(p.globalId));
+  if (p.globalId) {
+    x += tag("ram:GlobalID", escapeXml(p.globalId.value), { schemeID: p.globalId.schemeID });
+  }
   x += tag("ram:Name", escapeXml(p.name));
   if (p.description && atLeast(profile, "EN16931" /* EN16931 */))
     x += tag("ram:Description", escapeXml(p.description));
   if (p.legalOrganization) {
     let lo = "";
-    if (p.legalOrganization.id) lo += tag("ram:ID", escapeXml(p.legalOrganization.id));
+    if (p.legalOrganization.id) {
+      lo += tag(
+        "ram:ID",
+        escapeXml(p.legalOrganization.id),
+        p.legalOrganization.schemeID ? { schemeID: p.legalOrganization.schemeID } : void 0
+      );
+    }
     if (p.legalOrganization.tradingName)
       lo += tag("ram:TradingBusinessName", escapeXml(p.legalOrganization.tradingName));
     x += tag("ram:SpecifiedLegalOrganization", lo);
@@ -344,7 +352,11 @@ function buildLineItem(line, profile) {
   let doc = tag("ram:LineID", escapeXml(line.id));
   if (line.note) doc += tag("ram:IncludedNote", tag("ram:Content", escapeXml(line.note)));
   let prod = "";
-  if (line.standardIdentifier) prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier));
+  if (line.standardIdentifier) {
+    prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier.value), {
+      schemeID: line.standardIdentifier.schemeID
+    });
+  }
   if (line.sellerAssignedId) prod += tag("ram:SellerAssignedID", escapeXml(line.sellerAssignedId));
   if (line.buyerAssignedId) prod += tag("ram:BuyerAssignedID", escapeXml(line.buyerAssignedId));
   prod += tag("ram:Name", escapeXml(line.name));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackforge-eu/factur-x",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "type": "module",
   "description": "Embed Factur-X, ZUGFeRD, and XRechnung structured invoice XML into PDF/A-3 documents",
   "keywords": [