Answer to: where is the list of mandatory elements in UBL?
Blog entry: Submitted by gkholman on Wed, 2017-08-09 13:55. Last updated on Wed, 2017-08-09 13:57.
I was asked today "where is the list of mandatory elements in UBL?". Perhaps the answer will help others.
There can be no such list of mandatory elements in UBL. One cannot simply scrape the UBL document models looking for BIEs that have a minimum cardinality of one. Determining the list of mandatory elements is an iterative process.
Start at the top, work with what the mandatory elements are at the top-most set of children of the document element, decide which optional elements you need to use, then work down through the optional elements to see which children of those are mandatory. Repeat until done.
The reason you cannot just look in the model for everything that is documented as mandatory is because the context in which a mandatory BIE is found might, itself, be optional. For example, the ID child of PartyIdentification is mandatory:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_PartyIdentification.Details
... but the element is not mandatory in all invoices because PartyIdentification is optional in Party:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_Party.Details
Looking at the invoice,
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_Invoice.Details
... one sees five mandatory elements: ID, AccountingSupplierParty, AccountingCustomerParty, LegalMonetaryTotal and InvoiceLine.
If you bring up the invoice in the oXygen editing tool, these top-level elements are automatically reified. If you work with oXygen, I have published a Document Type Association for the oXygen tool at:
https://cranesoftwrights.github.io/resources/ubl/#oxygenubl
However, back to the invoice, there is a rule in UBL that no element can be empty:
http://docs.oasis-open.org/ubl/os-UBL-2.1/UBL-2.1.html#S-EMPTY-ELEMENTS
Since all of the elements of, for example, AccountingSupplierParty are optional:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_SupplierParty.Details
... you have to decide which one to use in the XML or the XML will not be conformant even though it will pass the schema. It cannot remain empty.
So say you decide you are going to use the Party child:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_Party.Details
It, too, cannot be empty but it has no mandatory children so you have to decide which optional child of Party you are going to include.
So say you decide you are going to use PartyIdentification ... then, all of a sudden, you have the mandatory element ID that you must use.
To summarize, there is no "list of mandatory elements" that will help you because some mandatory elements never come into play and it is mandatory that you choose which optional elements you are going to use in order to avoid a parent element from being empty.
There can be no such list of mandatory elements in UBL. One cannot simply scrape the UBL document models looking for BIEs that have a minimum cardinality of one. Determining the list of mandatory elements is an iterative process.
Start at the top, work with what the mandatory elements are at the top-most set of children of the document element, decide which optional elements you need to use, then work down through the optional elements to see which children of those are mandatory. Repeat until done.
The reason you cannot just look in the model for everything that is documented as mandatory is because the context in which a mandatory BIE is found might, itself, be optional. For example, the ID child of PartyIdentification is mandatory:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_PartyIdentification.Details
... but the element is not mandatory in all invoices because PartyIdentification is optional in Party:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_Party.Details
Looking at the invoice,
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_Invoice.Details
... one sees five mandatory elements: ID, AccountingSupplierParty, AccountingCustomerParty, LegalMonetaryTotal and InvoiceLine.
If you bring up the invoice in the oXygen editing tool, these top-level elements are automatically reified. If you work with oXygen, I have published a Document Type Association for the oXygen tool at:
https://cranesoftwrights.github.io/resources/ubl/#oxygenubl
However, back to the invoice, there is a rule in UBL that no element can be empty:
http://docs.oasis-open.org/ubl/os-UBL-2.1/UBL-2.1.html#S-EMPTY-ELEMENTS
Since all of the elements of, for example, AccountingSupplierParty are optional:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_SupplierParty.Details
... you have to decide which one to use in the XML or the XML will not be conformant even though it will pass the schema. It cannot remain empty.
So say you decide you are going to use the Party child:
http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_Party.Details
It, too, cannot be empty but it has no mandatory children so you have to decide which optional child of Party you are going to include.
So say you decide you are going to use PartyIdentification ... then, all of a sudden, you have the mandatory element ID that you must use.
To summarize, there is no "list of mandatory elements" that will help you because some mandatory elements never come into play and it is mandatory that you choose which optional elements you are going to use in order to avoid a parent element from being empty.
- gkholman's blog
- 10060 reads