change(s)-block in XML and in Notice Type Definitions

[gabrieledall]

Trying to understand the documentation of changes in changed notice-versions, I tried to reconstruct the XML-Structure from fields.json and compared it with its resembling Notice-types representation. To me, these two do not fit to each other:

A. XML-representation:

• Node - Parent-Node - BT - XPath - Repeatable?

• ND-Changes - ND-RootExtension - (-) - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes - N

• (-) - ND-Changes - BT-758-notice - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efbc:ChangedNoticeIdentifier - N

• ND-Change - ND-Changes - (-) - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes)/efac:Change - Y

• (-) - ND-Change - BT-13716-notice - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:Change/efbc:ChangedSectionIdentifier - N

• (-) - ND-Change - BT-141(a)-notice - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:Change/efbc:ChangeDescription - N

• (-) - ND-Change - BT-718-notice - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:Change/efbc:ProcurementDocumentsChangeIndicator - N

• (-) - ND-Change - BT-719-notice - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:Change/efbc:ProcurementDocumentsChangeDate - N

• (-) - ND-ChangeReason - ND-Changes - (-) - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:ChangeReason - N

• (-) - ND-ChangeReason - BT-140-notice -/*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:ChangeReason/cbc:ReasonCode - N

• (- ) - ND-ChangeReason - BT-762-notice - /*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:Changes/efac:ChangeReason/efbc:ReasonDescription - N

According to the XML-Representation, the ChangeNoticeIdentifier and the ND-ChangeReason-Node are seated in the Change-Section’s Root-Element “ND-Changes”, which is not repeatable and therefore should contain the following BTs:
BT-758,
BT-140,
BT-762

all other BT (BT-718, 719, 13716, 141 belong to the ND-Change-Node below, which is repeatable.

B. The Notice-Types representation looks differently:

The GR-Change-Group (not repeatable, should resemble to the ND_Changes-Node) and therefore containing
BT-758,
BT-140,
BT-762

but it also contains:
BT-718 + BT-719.

The GR-Change-Section (which is the only repeatable section in the View and therefore should resemble the ND-Change-Node) only contains
BT-13719 and
BT-141

I would have expected BT-718/9 belonging to the GR-Change-Section, instead.

[rousso]

Hi @gabrieledall,

Disclaimer: This is a quick answer. I have not actually looked at the specific fields you mention so maybe there is something there that I am missing.

Having said that, as a general principle, the structure in the notice type definition files is not supposed to be the same as the XML structure. In fact, the whole point of existence of the notice type definitions is that the XML structure is not (and should not) be the same as the visual structure on the screen. The XML structure is a data structure, whereas the notice type definitions provide a visual structure.

Therefore, (if I understood your notes correctly), your observation that the notice type definition presents a different structure from the XML structure is correct, but it should be expected because the differences are intentional.

Unfortunately, we have not yet been able to complete the SDK 1.0.0 documentation so many things are not properly clarified yet. But we are working n that. To mitigate this, I will give you a high level explanation of the logic behind that xmlStructure provided in fields.json and the notice type definition files provided in the notice-types folder.

The xmlStructure in fields.json

The point of the xmlStructure is to abstract the actual structure of XML elements included in the notices. It introduces the concept of a node which represents a location in the XML file. This location is expressed relative to the location of its parentNode via the xpathRelative property.

The xmlStructure is provided so that you can create a valid XML file without having to juggle with each and every XML element. For every repeatable XML element there is always a corresponding node in the xmlStructure indicated with repeatable: true.

Every field in fields.json has a parentNode. A field, like a node, also represents a location in the XML file. The location of the field in the XML file is (like a node) also indicated relative to the location of its parentNode via the xpathRelative property.

The notice type definitions in notice-types

The point of the notice type definition files is to tell your application how to put a form on the screen for the user to fill-in a notice. The end-user does not care about the intricacies and details of the XML representation. They need a simpler, conceptual representation of the notice which is structured closer to the way a human understands the notice, hiding the complexity of UBL requirements and XML data structures.

The notice type definition contains therefore a different hierarchy that cannot be based on the concept of node. Instead it is based on the notion of display-group (or simply termed group). In fact, the notice type definition contains a hierarchy of "content-items". There are two different types of "content-item": group and field.

A group is not a node. However, a group may be associated with a node. More specifically, if a group must be repeated on the screen for the user to fill the notice, then that repeatable group MUST be associated with a repeatable node (so that your application knows which XML elements need to be repeated in the generated XML notice). If a group is not associated with a node, then the group is not (and cannot be) repeatable.

In the notice type definitions, a content-item indicated with contentType: field, represents an HTML input control on the user's screen where the data for a specific field should be entered by the user.

I hope this helps. I will ask my colleagues to look into the specific examples you provide to check if there are any inconsistencies that I may have missed.

Regards,
Yannis

[gabrieledall]

Dear Yannis,

thank you for your answer which made me realize that we generally have the same understanding on the XML structure and the notice-type definitions (lucky me).
But the question I posed above still remains open with the release of SDK 1.1.0. May be my question was a bit too abstract to make you get my point and therefore I'll try angain:

How and where will the information on changes in the documents (and the date of change as well) be placed in the XML? The examples show that these information may be repeated in every section's detail information. Regarding the notice-types, this information might be added only once to the general changes definition.
Both might be correct on a procedural point of view but I supose, only one will be true. I still wonder which one would that be - the solution from the XML definition or the realization in the notice-types?

Could you please help once more?

Thank you in advance.
Gabriele