xsdSequenceOrder, help me to understand how to use it properly

[elerik]

Hi Lab
I have read Changelog and description of xsdSequenceOrder but when iam looking at

"id" : "BT-747-Lot",
"xpathAbsolute" : "/*/cac:ProcurementProjectLot[cbc:ID/@schemeName='Lot']/cac:TenderingTerms/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:SelectionCriteria/cbc:CriterionTypeCode[@listName='selection-criterion']",
"xpathRelative" : "cbc:CriterionTypeCode[@listName='selection-criterion']",
"xsdSequenceOrder" : [ { "cbc:CriterionTypeCode" : 2 } ],

I dont get it. I dont have enough knowladge to understand it at first sight.

for example expecting piece of xml for notice-subtype 16 is
<cac:ProcurementProjectLot>
<cbc:ID schemeName="Lot">LOT-0001</cbc:ID>
<cac:TenderingTerms>
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionContent>
<efext:EformsExtension>
<efac:SelectionCriteria>
<cbc:CriterionTypeCode listName="selection-criterion">sui-act</cbc:CriterionTypeCode>
</efac:SelectionCriteria>
<efac:SelectionCriteria>
<cbc:CriterionTypeCode listName="selection-criterion">tp-abil</cbc:CriterionTypeCode>
</efac:SelectionCriteria>
<efac:SelectionCriteria>
<cbc:CriterionTypeCode listName="selection-criterion">ef-stand</cbc:CriterionTypeCode>
</efac:SelectionCriteria>
</efext:EformsExtension>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
</cac:TenderingTerms>
</cac:ProcurementProjectLot>

How can xsdSequenceOrder help me identify efac:SelectionCriteria as a place which is necessary create again for 3 different values.

in previous version 1.6.x was relative path
"xpathRelative" : "efac:SelectionCriteria/cbc:CriterionTypeCode[@listName='selection-criterion']",
which was usable as identificator where should i create new child node. But in 1.7 there is nothing like that in case "id" : "BT-747-Lot",

for example field "id" : "BT-743-Lot",
stayed same.
v1.7
"xpathRelative" : "cac:ContractExecutionRequirement/cbc:ExecutionRequirementCode[@listName='einvoicing']",
"xsdSequenceOrder" : [ { "cac:ContractExecutionRequirement" : 38 }, { "cbc:ExecutionRequirementCode" : 3 } ],

v1.6
"xpathRelative" : "cac:ContractExecutionRequirement/cbc:ExecutionRequirementCode[@listName='einvoicing']",

Iam not going to lie. Iam little bit confused. Thank you for more detail explanation. what is goal, Can I expect that xPathrelative will be simplified in future and xsdSequenceOrder will control or BT-747-Lot xPathRelative missing half of it and so on. Thank you :)

[rouschr]

Hello,

good question.
To understand this you have to look into the XSDs.
Here the fields.json is making the link between fields/nodes and the order of XML elements as defined in the XSDs.
Example:

<xsd:complexType name="SubcontractingTermType">
		<xsd:sequence>
			<xsd:element ref="efac:FieldsPrivacy" minOccurs="0" maxOccurs="unbounded"/>
			<xsd:element ref="efbc:TermAmount" minOccurs="0" maxOccurs="1"/>
			<xsd:element ref="efbc:TermDescription" minOccurs="0" maxOccurs="unbounded"/>
			<xsd:element ref="efbc:TermPercent" minOccurs="0" maxOccurs="1"/>
			<xsd:element ref="efbc:TermCode" minOccurs="1" maxOccurs="1"/>
			<xsd:element ref="efbc:PercentageKnownIndicator" minOccurs="0" maxOccurs="1"/>
			<xsd:element ref="efbc:ValueKnownIndicator" minOccurs="0" maxOccurs="1"/>
		</xsd:sequence>
	</xsd:complexType>

Under SubcontractingTerm the element efac:FieldsPrivacy is at first place (order 1, no matter how many there are)
Under SubcontractingTerm the element efbc:TermAmount is at first place (order 2)
...

For repeating elements of the same type the sort order among themselves does not matter. Also for attributes the order does not matter.
So the point of providing the xsdSequenceOrder is to avoid all the XSD parsing work if you use the SDK, it has already been extracted for you. The principle is that you must find all children under a parent and lookup the sort order of XML child elements.
For repeating elements of the same kind under the same parent the order does not matter.

Assuming siblingA, siblingB and siblingC are all under the same kind of parent element (in the example above it would something like SubcontractingTermType).
Assuming they are not in the correct order in your XML.
Each XML element name has a given sort order, given by the sequence in one of the XSD files, so in pseudo json:
[{siblingA : 2}, {siblingB : 1}, {siblingC : 3}, ...]
Would be something like this in the example:
[{"efbc:TermAmount" : 2}, {"efac:FieldsPrivacy" : 1}, {"efbc:TermDescription" : 3}, ...]

Sorting sibling order before using it to sort the elements:
[{siblingB : 1}, {siblingA : 2}, {siblingC : 3}, ...]

Then remove sibling B, add it back in the children at position 1, remove sibling A remove 2 and add it back ...
So in the end you would have:

parent
    siblingA
    siblingB 
    siblingC 
    ...

This is to match the XSD sequence and pass XSD validation.
Of course this is not the full algorithm but this is the main logic, you want to replicate the order found in the XSDs.
The editor demo will provide a demonstration on how to use this sort order, I recommend to wait for version 1.8 to fully use the sort order along with the editor demo. You can see the current progress on this here:
https://github.com/OP-TED/eforms-notice-editor/blob/feature/TEDEFO-1913-use-of-fields-json-xsd-sequence-order/src/test/java/eu/europa/ted/eforms/noticeeditor/helper/notice/NoticeXmlTagSorterTest.java
And a preview of the latest fields.json of future 1.8:
fields.zip

[elerik]

chm.
Than I compare those two field directly.
BT-747-Lot - 1.7
"xpathRelative" : "cbc:CriterionTypeCode[@listName='selection-criterion']",
"xsdSequenceOrder" : [ { "cbc:CriterionTypeCode" : 2 } ],
where cbc:CriterionTypeCode only once.
But for subtype 16 i need it 3x in specific nodes.
Should not be xsdSequenceOrder looks similar to xPathRelative is like in 1.6 ? so
"xpathRelative" : "efac:SelectionCriteria/cbc:CriterionTypeCode[@listName='selection-criterion']",
and then
"xsdSequenceOrder: [ { "efac:SelectionCriteria": 20}, { "cbc:CriterionTypeCode" : 2 } ],

like for
BT-743-Lot
"xpathRelative" : "cac:ContractExecutionRequirement/cbc:ExecutionRequirementCode[@listName='einvoicing']",
"xsdSequenceOrder" : [ { "cac:ContractExecutionRequirement" : 38 }, { "cbc:ExecutionRequirementCode" : 3 } ],
where cac:ContractExecutionRequirement unlimited ammount.
where cbc:ExecutionRequirementCode only once.
This is ok. This said exactly what i need to know.

or
"id" : "OPP-070-notice"
"xpathRelative" : "efac:NoticeSubType/cbc:SubTypeCode",
"xsdSequenceOrder" : [ { "efac:NoticeSubType" : 17 }, { "cbc:SubTypeCode" : 1 } ],

[rouschr]

Here is 16.json as it will be (or close) in SDK 1.8, as you can see some sections have been reworked to help with XML generation:
16.zip