Home

Awesome

DDD

javadoc Maven Central

Document Details Determinator - determine VESIDs from payload to use with https://github.com/phax/phive and https://github.com/phax/phive-rules

This project helps to determine the VESID from arbitrary payloads. Currently only XML payloads are supported.

This project is part of my Peppol solution stack. See https://github.com/phax/peppol for other components and libraries in that area.

Concept

A set of relevant fields for business documents is defined. Currently these are (see enum EDDDSourceField):

These fields are to be determined differently depending on a specific syntax (see class DDDSyntax). Each syntax is uniquely determined by the combination of the XML root element namespace URI and local name.

DDD offers a mapping of the above mentioned fields on a set of predefined syntaxes (in alphabetical order):

The goal is to deduce certain (missing) values based on other values (class DDDValueProviderPerSyntax). The deducible values are currently (in enum EDDDDeterminedField):

How to use it

The entry point is the class DocumentDetailsDeterminator which requires an instance of DDDSyntaxList and an instance of DDDValueProviderList. DDD ships with a predefined list of syntax mappings. The default syntax mapping is created via DDDSyntaxList.getDefaultSyntaxList (). DDD also ships with a predefined list of value providers. The default value provider is created via DDDValueProviderList.getDefaultValueProviderList (). Both syntax mapping and value providers are read-only objects and may only be created once.

So the simplest way to create a new DocumentDetailsDeterminator is like this:

final DocumentDetailsDeterminator aDDD = 
   new DocumentDetailsDeterminator (DDDSyntaxList.getDefaultSyntaxList (),
                                    DDDValueProviderList.getDefaultValueProviderList ());

This object can be used to determine multiple document details via the following API:

final Element aRootElement = ...;
final DocumentDetails aDD = aDDD.findDocumentDetails (aRootElement);
// aDD may be null

The variable aRootElement indicates a org.w3c.dom.Element node representing the document to be determined. The resulting details are in the object aDD of type DocumentDetails.

Syntaxes

DDD is about determining XML document types, so the determination of the overall syntax is based on the root element namespace URI and local element name.

So e.g. for the following file snippet

<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
    xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
    xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  ...    
</Invoice>

The root element namespace URI is urn:oasis:names:specification:ubl:schema:xsd:Invoice-2 and the local element name is Invoice.

Each syntax has the following properties:

FieldID
Customization IDCustomizationID
Process IDProcessID
Business Document IDBusinessDocumentID
Sender ID SchemeSenderIDScheme
Sender ID ValueSenderIDValue
Sender NameSenderName
Sender Country CodeSenderCountryCode
Receiver ID SchemeReceiverIDScheme
Receiver ID ValueReceiverIDValue
Receiver NameReceiverName
Receiver Country CodeReceiverCountryCode

The XML Schema for syntax list can be found at https://github.com/phax/ddd/tree/main/src/main/resources/schemas

Adding custom syntaxes

The default syntax list is included inside DDD. It can be accessed via DDDSyntaxList.getDefaultSyntaxList ().

To add new syntaxes, you need to provide your own rule file, and read it via DDDSyntaxList.readFromXML. Afterwards, the default list and the newly read syntax list can be merged via DDDSyntaxList.createMergedSyntaxList.

Please note that when merging syntax lists, each syntax must be unique. There is no overwriting, just adding of syntaxes.

Value Providers

The DDD Value Providers determines the specific "profile" or "subsets" of a syntax, based on one or more specific values.

E.g. for the syntax "UBL 2.x Invoice", if the CustomizationID has the value urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0 than it is an "XRechnung UBL Invoice 3.0" which uses syntax version 2.1 and the VESID for validation is de.xrechnung:ubl-invoice:3.0.2.

The XML Schema for value provider list can be found at https://github.com/phax/ddd/tree/main/src/main/resources/schemas

Adding custom value providers

The default syntax list is included inside DDD. It can be accessed via DDDValueProviderList.getDefaultValueProviderList ().

To add new value providers, you need to provide your own rule file, and read it via DDDValueProviderList.readFromXML. Afterwards, the default list and the newly read value provider list can be merged via DDDValueProviderList.createMergedValueProviderList.

Please note that when merging value provider lists, the lists are woven into each other. However, specific profiles existing in one list cannot be overwritten by the other list. The lists can only extend each other.

Maven usage

Add the following to your pom.xml to use this artifact, replacing x.y.z with the latest version:

<dependency>
  <groupId>com.helger</groupId>
  <artifactId>ddd</artifactId>
  <version>x.y.z</version>
</dependency>

News and noteworthy

My personal Coding Styleguide | It is appreciated if you star the GitHub project if you like it.