Extensies in DICO

Versiebeheer deze pagina

Date	Version	By	Explanation changes
1-1-2022	v1.0	Jos Hebing Luuk d'Hooghe Herman Drenth	• First publication
1-12-2023	v2.0	Luuk d'Hooghe Herman Drenth	• Merge all documentation on extensions • Technical application UDE in DICO • Split documentation per extension

1 Introduction

This manual contains the general ground rules for companies in the construction and installation sector that want to exchange standardised and electronic messages and that deal with data not included in the basic version of the DICO messages.

The DICO Standard consists of various components and sub-areas. For example, the data extension has an overlap with the Data Message Set. In addition, the DICO Standard also has the Maintenance messages, the Transaction messages and the Rental messages.

This chapter attempts to describe the process and use of extensions in SALES005.

1.1 What is the purpose of this document?

This document describes the overarching agreements made within the industry on the use of DICO extensions. This process model is intended for the mentioned extension and provides an overview of the ground rules that apply within the DICO Standard.

1.2 Which documents are part of the user documentation?

The user documentation for the extensions consists of two documents: a process description for use and ground rules, and a technical part for each extension. The latter part is published on Semantic Treehouse.

The documentation has been compiled with care; however, in the unlikely event of errors or ambiguities, you are requested to contact Chain Standard for clarification. Please do not make your own interpretation, to avoid dialects of the standard. The documentation describes the scope, process and technical principles of the DICO Standard. A licence is required for the actual exchange of DICO messages. For more information and terms of use on this, see the website of Chain Standard.

1.3 Compilers

This document is maintained by Ketenstandaard Bouw en Techniek. Chain Standard Construction and Engineering manages the DICO Standard and facilitates DICO Committees for the Construction and Installation sector. Companies from the sector are represented within these committees, ensuring connection to the sector's information needs.

For questions or comments on this document, please contact dico@ketenstandaard.nl. 

2 Rules and guidelines DICO Extensions

Extensions were instituted by the then SALES Committee at the release of the DICO SALES005 version to allow elements and fields to be added to an existing message at a later date, without requiring changes to the pre-existing XSD of the message in question. This simultaneously brings version-level stability and creates sufficient flexibility to support omissions or new market needs though.

Ketenstandaard distinguishes between official DICO extensions and non-DICO extensions. The official DICO extensions have been created through the usual procedures in the management document, are recognised by Ketenstandaard and as such are also part of the DICO Standard. The starting point here is that such extensions will always be optional, as a recipient may not use the extension.

Non-DICO extensions are not supported by Ketenstandaard and are not part of the DICO Standard. A non-DICO extension is a purely bilateral arrangement, use of such an extension is always voluntary. Ketenstandaard encourages non-DICO extension initiatives to be submitted as RFCs to achieve a market-wide solution. If this does not happen, the market runs the risk of still developing many bilateral solutions and undermining the benefit of a standard.

DICO extensions are:

• Officially supported by Chain Standard;
• Developed in consultation with the market and committees;
• Established through established procedures;
• Optional for users;
• To be validated via an additional XSD offered by Ketenstandaard;
• Incorporated in relevant tools of Ketenstandaard, such as a validation tool;
• Offer the possibility to connect new processes, market requirements and/or market parties to the DICO Standard.

Non-DICO extension (bilateral extension) are:

• Not supported by Chain Standard
• 100% bilateral agreement; as this extension is not part of the standard, third parties cannot be expected to use this extension
• This solution is not recommended by Ketenstandaard because it encourages bilateral solutions;
• A non-official extension can be made official; the usual procedures also apply to this and it will be treated as a 'new RFC'. However, this is not the desirable process.

There are 'User Defined Extension' elements in various places in the SALES005 messages. Theoretically, any extension (both official and unofficial extensions) can be applied in any place where a User Defined Extension appears in the messages. Each extension will therefore describe where and how it should be applied. After all, it is undesirable for an extension that is designed to add extra invoice information to the invoice message to also be used in the article message. It will be examined for each extension whether it will get a fixed place in the standard. For industry-specific extensions, it may be desirable to keep them external because they have no relevance to the other industries, whereas generic matters may be useful to several parties..

2.1 Toepassen extensie binnen DICO

A separate XSD is created for each application (extension). Applying the extension in this way ensures that:

a. Prefixes to be defined can potentially conflict with bilateral solutions. b. Adoption of bilateral solutions can be very easy c. Simple versioning d. Clearly separated functionality e. Technically possible within current agreements f. Easy to implement

In case of conflicts with bilateral solutions, Chain Standard will indicate that the DICO Standard and thus the official extensions always prevail over bilateral agreements.

2.2 Products

An official DICO extension always consists of at least the following components:

• An XSD or an update of an existing extension XSD;
• Version numbering;
• Process documentation;
  • Permitted application in XML;
  • Description of the intended process;
• Technical documentation (example xml)
• Usage rules

If there is a deviation from the existing process then the process of the extension used applies.

2.3 Procedure for changes

• If market parties find that information is missing or a process is not supported, they will consult with Ketenstandaard;
• Together with Ketenstandaard they investigate where the need all lives in the market;
• It is determined whether the need should be solved with an extension or a new message or in a subsequent version of the DICO Standard;
• Together with Ketenstandaard they draft an RFC request. This request is supported with:
  • Substantiation of the need
  • Draft process description
  • Optional: draft XSD
  • Optional: draft XML

The above is in line with the "normal" process regarding RFCs.

2.4 Additional points/principles

The goal is at all times that an original message remains usable at the time the recipient does not use the extension, an extension should not break the original message.

• The goal is to keep the number of extensions to a minimum, as adoption of an extension is not guaranteed.
• Extensions are within the scope of the current process and cannot be solved using other fields/elements, other standards or other methods.
• Sector-specific extensions add an unsupported process or information to the existing standard.

2.5 Technical application UDE within DICO

2.5.1 Use of extension in one message

If an extension is applied then a separate header must be declared. Its position is determined by the <UserDefinedExtension> field in the message. This field appears in several places in a message. Chain Standard determines the exact location where which extension should be applied.

If an extension is then used then a header must be applied. Below is an example of such a header, in this case for the use of a Transaction extension (TransactionUDE):

<UserDefinedExtension xmlns:trans="http://www.ketenstandaard.nl/UDE/SALES/Transaction/v1" xsi:schemaLocation="http://www.ketenstandaard.nl/UDE/SALES/Transaction/v1 TransactionUDEv1.xsd">

Below is another example, now within a strucuture of the DICO Order message. In this case, the Equipment Rental extension is used in the order message. The extension also has a different prefix (rental:) than the DICO message.

<OrderLine>
  <LineNumber>2</LineNumber>
  <OrderedQuantity>5</OrderedQuantity>
  <OrderedQuantityUoM>PCE</OrderedQuantityUoM>
  <LineIdentification>0002</LineIdentification>
  <TradeItemIdentification>
    <GTIN>08718851294272</GTIN>
    <AdditionalItemIdentification>
      <TradeItemDescription>Betonmolen, elektrisch - 145 l</TradeItemDescription>
    </AdditionalItemIdentification>
  </TradeItemIdentification>
  <UserDefinedExtension xmlns:rental="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2"
    xsi:schemaLocation="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2 RentalUDEv2.xsd">
    <rental:RentalUDE>
      <rental:RentalPeriod>
        <rental:FixedStartDateTime>2021-03-01T00:01:00+01:00</rental:FixedStartDateTime>
        <rental:FixedFinishDateTime>2021-03-16T23:59:00+01:00</rental:FixedFinishDateTime>
      </rental:RentalPeriod>
    </rental:RentalUDE>
  </UserDefinedExtension>
</OrderLine>

2.5.2 Using multiple extensions in one message

Multiple extensions may be used in a specific place in a message. Example of the header with the use of 2 different extensions. In this case, the DataUDE and the RentalUDE:

<UserDefinedExtension xmlns:rental="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2" xmlns:data="http://www.ketenstandaard.nl/UDE/SALES/Data/v2" xsi:schemaLocation="https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2 RentalUDEv2.xsd http://www.ketenstandaard.nl/UDE/SALES/Data/v2 DataUDEv2.xsd">

2.6 Overview of published DICO Extensions

Name	Version XSD	Namespace	Function of the UDEs
DataUDE	DataUDE.xsd	http://www.ketenstandaard.nl/UDE/SALES/Data/v1	TradeItemIndicators
	DataUDEv2.xsd	http://www.ketenstandaard.nl/UDE/SALES/Data/v2	TradeItemIndicators Indicator ValueDetail ModelClassificationCharacteristics VariableOrderConditions
RentalUDE	RentalUDE.xsd	https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v1	Prices WeekendInvoicing ContinuesUse RentalPeriod StartRentalPeriod
	RentalUDEv2.xsd	https://ontology.ketenstandaard.nl/DICO/UDE/Rental/v2	Prices WeekendInvoicing ContinuesUse RentalPeriod StartRentalPeriod
TransactionUDE	TransactionUDEv1.xsd	http://www.ketenstandaard.nl/UDE/SALES/Transaction/v1	TransportInformation
EnergyUDE	EnergyUDEv1.xsd	https://ontology.ketenstandaard.nl/DICO/UDE/Energy/v1	nvt