DeltaXML Integration Guide

1. Overview

The Worldbox WB Delta format packages the differences between two XML documents

Document A (baseline) and Document B (updated) into a single, well-formed XML file. The generated delta is changes-only: unchanged data is omitted so downstream systems can focus strictly on edits, additions, or deletions.

Key goals of the current implementation:

minimize false positives when list items shift (e.g. shareholder or phone arrays);
surface granular differences at the most relevant hierarchy (e.g. CompanyStatuses, not entire Predicates trees);
keep noise out of comparisons by ignoring volatile attributes such as @nr.

Attribute @nr is omitted in the delta to avoid false positive changes, e.g if a Manager is deleted the content will be shifted and the attribute @nr will be changed for all of remaining, triggering a false positive change.

2. Anatomy of a WB Delta Document

This guide explains the structure of the WB Delta output and provides actionable steps for clients mapping the delta to their own schemas or change processors.

2.1 Root Element

<wbdata xmlns:wbdata="http://www.worldbox.net/xml/well-formed-delta"
        wbdata:delta="A!=B"
        wbdata:version="2.0"
        wbdata:content-type="changes-only">
    ...
</wbdata>

Attribute	Value	Meaning
`xmlns:wbdata`	Fixed URI	Namespace for delta-specific attributes and helper elements.
`wbdata:delta`	`A!=B`	Indicates the overall document differs between baseline and update.
`wbdata:version`	`2.0`	Version of the WB Delta schema.
`wbdata:content-type`	`changes-only`	Only changed fragments are present.

3. Change Semantics (`wbdata:delta` Values)

Value	Interpretation
`A=B`	Data identical in both documents. Included only when useful for hierarchy.
`A!=B`	Data exists in both, but content differs (text, nested nodes, or attributes).
`A`	Data exists only in Document A (removed in Document B).
`B`	Data exists only in Document B (added in Document B).

Rules:

A and B versions retain the full element structure as it appeared in that document.
When an element is marked A!=B, its children expose the precise changes. Unchanged siblings may be omitted to keep the file concise.
Nested wbdata:delta="A=B" nodes can appear under changed parents to preserve context where needed.
E.g LegalForm has no changes but CompanyStatus has changes under Predicates parent
<Predicates wbdata:delta="A!=B"> <Predicate wbdata:delta="A!=B"> <LegalForms wbdata:delta="A=B"/> <CompanyStatuses wbdata:delta="A!=B" wbdata:ordered="false">

4. Container Handling and Ordering Rules

4.1 Orderless Containers

Certain collections should be treated as unordered so that insertions or deletions do not trigger mismatched comparisons. These containers carry wbdata:ordered="false" whenever changes are present:

Path (Parent → Child)	Rationale
`wbdata` → any top-level tag (except `Comm`, `Predicates`, `CompanyFigures`, `GroupFigures`)	Document-level lists (e.g. `Names`, `Addresses`).
`Comm` → `Phones` / `Mobiles` / `Faxes` / `Homepages` / `Emails`	Contact lists where sequence is not meaningful.
`Predicate` → `LegalForms` / `CompanyStatuses`	Multi-valued attributes.
`CompanyFigure` → `AnnualFigures`	Specific year-based breakdowns.
`GroupFigure` → `AnnualFigures`	Same as above for group context.

Refer to section 8 for full table details

4.2 Granular Comparison Levels

Predicates: compare at Predicate + CompanyStatuses level instead of marking the full Predicates block as changed.
CompanyFigures / GroupFigures: examine AnnualFigures separately from ActualFigures to prevent whole nodes from being flagged when a single year changes.

These rules match the XSLT preprocessing that sets deltaxml:ordered="false" on the same hierarchies, ensuring consistent behavior across tooling.

4.3 Singular Objects

Path	Rationale
`Ident`	Singular Object - comparison on tag level
`Crossborder`	Singular Object - comparison on tag level
`RealEstate`	Singular Object - comparison on tag level

4.4 Special nodes

Special Handling: Company & Group Figures

The CompanyFigures and GroupFigures nodes exhibit mixed comparison behavior. Unlike standard unordered lists, the top-level containers maintain strictly ordered comparisons, while specific sub-containers are treated as unordered sets to allow for precise year-by-year matching.

Key Comparison Behaviors

Ordered Parents (Sequence Match): The root containers CompanyFigures and GroupFigures, as well as their direct children (CompanyFigure, GroupFigure), do not carry the wbdata:ordered="false" attribute. They are compared strictly by their sequence in the document.
The AnnualFigures container within these blocks is an exception. It is explicitly marked as wbdata:ordered="false".
- Action: Clients must match AnnualFigure records by unique @id (identifying the specific fiscal year) rather than their list position.

Integration Requirement

Clients must be prepared to parse wbdata:textGroup elements within standard data fields. When a field is marked wbdata:delta="A!=B", it will contain grouped text nodes showing the 'before' (A) and 'after' (B) values.

Example: Inline Field Update

In the example below, the EmployeesValue has changed. Rather than removing and re-adding the entire EmployeesValue node, the delta provides an inline view of the change:

  <CompanyFigures wbdata:delta="A!=B">
    <CompanyFigure wbdata:delta="A!=B">
      <WIN wbdata:delta="A=B"/>
      <Name wbdata:delta="A=B"/>
      <TradeName wbdata:delta="A=B"/>
      <ActualFigures wbdata:delta="A!=B">
        <PeriodEndYear wbdata:delta="A=B"/>
        <EmployeesRangeCode wbdata:delta="A=B"/>
        <EmployeesRange wbdata:delta="A=B"/>
        <EmployeesValue wbdata:delta="A!=B">
          <wbdata:textGroup wbdata:delta="A!=B">
            <wbdata:text wbdata:delta="A">25601</wbdata:text>
            <wbdata:text wbdata:delta="B">28601</wbdata:text>
          </wbdata:textGroup>
        </EmployeesValue>
        <SalesRangeCode wbdata:delta="A=B"/>
        <SalesRange wbdata:delta="A=B"/>
        <Sales wbdata:delta="A=B"/>
        <SalesCurrencyCode wbdata:delta="A=B"/>
        <SalesCurrency wbdata:delta="A=B"/>
        <Estimated wbdata:delta="A=B"/>
      </ActualFigures>
      <AnnualFigures wbdata:delta="A=B"/>
    </CompanyFigure>
  </CompanyFigures>

5. Record-Matching Behavior

Client recommendation: whenever possible, match by @id in downstream systems to determine if it’s a change, added a new child node or deleted a child node. (see samples below)

6. Common Change Patterns and Examples

6.1 Change

<Ident wbdata:delta="A!=B" wbdata:ordered="false">
	<Line1 wbdata:delta="A">Walliselen 6</Line1>
	<Line1 wbdata:delta="B">Banhofstarsse 12</Line1>
</Ident>

Interpretation: street line updated. Use the wbdata:text children to display old vs new content.

The Ident section is a singular object , therefore changes are compared in the sequence line by line and not in container level.

6.1.2 Deletion

<Ident wbdata:delta="A!=B" wbdata:ordered="false">
	<Line1 wbdata:delta="A">Walliselen 6</Line1>
</Ident>

Interpretation: Line1 has been removed, exists only in document A but does not exists in document B

6.1.3 Add

<Ident wbdata:delta="A!=B" wbdata:ordered="false">
	<Line1 wbdata:delta="B">Banhofstarsse 12</Line1>
</Ident>

Interpretation: Line2 has been added, exists only in document B but does not exists in document A

6.3 Classification change in an nested orderless container

<Comm wbdata:delta="A!=B">
  
    <Phones wbdata:delta="A!=B" wbdata:ordered="false">
      <Phone wbdata:delta="A" id="1" status="1">
        <Name>MAIN</Name>
        <Nr>+931 2747 5212</Nr>
      </Phone>
      <Phone wbdata:delta="A" id="2" status="1">
        <Name>MAIN</Name>
        <Nr>+752 2747 5003</Nr>
      </Phone>
      <Phone wbdata:delta="B" id="1" status="1">
        <Name>MAIN</Name>
        <Nr>+931 2747 5213</Nr>
      </Phone>
      <Phone wbdata:delta="B" id="2" status="1">
        <Name>MAIN</Name>
        <Nr>+752 2747 5004</Nr>
      </Phone>
    </Phones>
    <!-- End of Phones containers -->
  
    <Mobiles wbdata:delta="A=B"/>
  
    <!-- Start of Faxes containers -->
    <Faxes wbdata:delta="A!=B" wbdata:ordered="false">
      <Fax wbdata:delta="A" id="1" status="1">
        <Name>MAIN</Name>
        <Nr>+752 2810 6564</Nr>
      </Fax>
      <Fax wbdata:delta="A" id="2" status="1">
        <Name>MAIN</Name>
        <Nr>+752 2596 0826</Nr>
      </Fax>
      <Fax wbdata:delta="B" id="1" status="1">
        <Name>MAIN</Name>
        <Nr>+752 2810 6563</Nr>
      </Fax>
      <Fax wbdata:delta="B" id="2" status="1">
        <Name>MAIN</Name>
        <Nr>+752 2596 0825</Nr>
      </Fax>
    </Faxes>
  
    <Homepages wbdata:delta="A=B"/>
  
    <Emails wbdata:delta="A=B"/>
  
</Comm>

Interpretation: When a change happens in the Comm section in order to not trigger the whole section as a change, we apply Orderless flag(wbdata:ordered="false") in each sub child lists (Phones, Mobiles, Faxes,Homepages and Emails) indicating consumers should treat the set as a bag, not a sequence.

The key is to look at the id attributes within the <Phones> and <Faxes> etc. containers.

Match IDs: Notice that every item marked wbdata:delta="A" (the "before" version) has a matching item marked wbdata:delta="B" (the "after" version) with the same id.
- <Phone id="1"> has both an A and a B version.
- <Phone id="2"> has both an A and a B version.
- The same pattern exists for <Fax id="1"> and <Fax id="2">.
It's an Update: Because every A record has a corresponding B record with the same ID, it signals an update. You should find the record in your system with that id and replace its data with the new data from the B version.
No Deletions or Additions:
- If a record was deleted, there would be an A record with no matching B record.
- If a record was added, there would be a B record with no matching A record.
- Since neither of those is true here, you only need to perform updates.
No Change: The <Mobiles>, <Homepages>, and <Emails> sections are marked A=B, meaning "identical." You can safely ignore them.

7. Consuming the Delta in Client Systems

Namespace Awareness: retain the wbdata namespace; check wbdata:delta on every node encountered. Namespaces should not be stripped during parsing.
Process Orderless Containers as Sets: when wbdata:ordered="false" is present, compare items based on @id attribute
Map Change Types:
- A: treat as removal.
- B: treat as addition.
- A!=B: treat as update. Inspect child elements to extract precise field-level differences.
Handle Text Groups: wbdata:text children carry the old and new values. Always inspect both entries to display change history accurately (only in CompanyFigures and GroupFigures).

8. Node Matching Reference

Node Path	Comparison Type	Child Element	Match Key (Identifier)	Notes
`Ident`	Singular Object	N/A	Tag Name	Always present if changed; match by tag.
`Names`	Unordered Set	`Name`	`@id`
`Addresses`	Unordered Set	`Address`	`@id`
`Comm`	Wrapper Object	N/A	Tag Name	container for specific comm types.
`Comm/Phones`	Unordered Set	`Phone`	`@id`
`Comm/Mobiles`	Unordered Set	`Mobile`	`@id`
`Comm/Faxes`	Unordered Set	`Fax`	`@id`
`Comm/Homepages`	Unordered Set	`Homepage`	`@id`
`Comm/Emails`	Unordered Set	`Email`	`@id`
`Predicates`	Wrapper Object	`Predicate`	Tag Name	Contains only one `Predicate` block.
`.../LegalForms`	Unordered Set	`LegalForm`	`@id`
`.../CompanyStatuses`	Unordered Set	`CompanyStatus`	`@id`
`IdKeys`	Unordered Set	`IdKey`	`@id`
`Histories`	Unordered Set	`History`	`@id`
`Naces/Naces`	Unordered Set	`Nace`	`@id`
`.../BusinessLines`	Unordered Set	`BusinessLine`	`LineOfBusinessCode`	Usually lacks `@id`; match by code, or by sequence of Nace codes (they come together)
`//Texts`	Unordered Set	`Text`	`@id`	Applies to all text blocks; `ActivityText`, `RegText`, `NewsText`… etc.
`Crossborder`	Singular Object	N/A	Tag Name
`Banks`	Unordered Set	`Bank`	`@id`
`Securities`	Unordered Set	`Security`	`@id`
`RegOffices`	Unordered Set	`RegOffice`	`@id`
`Domiciles`	Unordered Set	`Domicile`	`@id`
`Agendas`	Unordered Set	`Agenda`	`@id`
`Directors`	Unordered Set	`Person`	`@id`
`OfficialPositions`	Unordered Set	`Person`	`@id`
`ExternalPositions`	Unordered Set	`Person`	`@id`
`Managers`	Unordered Set	`Person`	`@id`