Submitted by Xalgorithms Foundation https://www.xalgorithms.org/
Contact: Joseph Potvin, Executive Director, Mobile: 819-593-5983, email@example.com
This text arises from 100% free/libre/open source work-in-progress by Xalgorithms Foundation https://www.xalgorithms.org/
and is dual-licensed under the "OASIS Feedback License" and the "Creative Commons Attribution 4.0 International License".
The purpose of this proposal is to intiate discussion about the utility of including document version history and associated causality within UBL, and to explore alternative approaches to implementing this capability. Xalgorithms Foundation would contribute technical specifics to move this proposal rapidly forward in accordance with feedback and guidance from the UBL community and its TC.
We anticipate that implementation would require a new namespace, several new elements, and a new document type. Our proposal makes reference to some non-UBL XML schemas to illustrate our intent with examples. However it remains to determine which elements of their approaches and particular technical structures from these references might be adapted to UBL.
The business reason for adding document version history and associated causality are described here with regard to the UBL invoice, which is a particular requirement of the authors: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd
However the authors anticipate that this capability might be most usefully considered as applicable to several UBL document types.
2. EXAMPLE: UTILITY OF INVOICE VERSION HISTORY
Within a set of rules, a buyer and a seller trade goods and services at a price. Some of those rules come into a transaction from sources other than the buyers and sellers themselves—from governments, loyalty programs, data providers, accounting standards, and financial intermediaries. The velocity of each transaction, as in air travel, depends significantly on the “baggage handling efficiency” associated with it. The more time and effort that a transaction requires to be executed as a whole, including all the baggage that must go with it, the higher its procedural cost will be. Transaction time and cost can be dramatically reduced by automating the computational rules invoked by each transaction, such as taxes, duties, price benchmarks, loyalty programs, data constraint notifications, reporting, messaging, etc.
Consider a network service that accepts UBL invoice data, then finds and fetches external rules, and issues an updated UBL invoice with an extended data package that includes all applicable taxes, duties, points, a price coefficient if algorithmic pricing is specified in the contract, and so on. The output would be a more complete UBL invoice document.
Version history and change causality of an invoice document are not the same as the status of the invoice in the context of busine workflow (e.g. whether it is paid). The UBL schema already accommodates business processes. The present proposal is focused upon the incremental assembly of the invoice itself. Following are some considerations:
- An invoice is dynamic until until a transaction is executed against it, at which point it becomes an audit record with legal significance.
- The invoice must remain atomic so that element changes can be separately tracked. It should be possible to sign only parts of an invoice, and to accept multiple signatures. (A blockchain ledger might make sense here.)
- A new top level element could be "change history" in a new namespace, the use of which would be optional.
- Documentation of change causality can be added to each subsequent version, as part of the new version.
3. DELTA: XML DOCUMENT VERSION HISTORY
Caveat: The references in this section describe multiple ways of implementing XML document version history. The present proposal does not yet recommend an optimal versioning solution for UBL.
Sonawane, V. R., & Rao, D. R. (2015). A Comparative Study: Change Detection and Querying Dynamic XML Documents. International Journal of Electrical and Computer Engineering, 5(4), 840. https://www.iaesjournal.com/online/index.php/IJECE/article/viewFile/7702/4049
Lead author: "Vijay Sonawane" <firstname.lastname@example.org
"Dynamic XML documents are applicable in many fields of information management and create the demand that it should support multi-version documents. Therefore it is necessary to store different versions of XML documents with time. Storage of all the versions of an XML document is not an effective solution as it increases the duplication and makes searching and querying harder on growing document. So it is essential to find techniques to store and detect the changes in multiversion XML documents. Its also important to find schemes to efficiently execute the cross version queries over dynamic of XML document. ... Delta document records the changes between two consecutive versions. Using delta one can easily locate its previous version so it has been considered that the delta approach is superior to the object referencing approach.
More from these authors: https://scholar.google.com/citations?user=6T4PSqEAAAAJ&hl=en
The sequence of changes involved in advancing from one version to the next might be important to the outcome. "Synchronized Multimedia Integration Language" (SMIL) Timing is the W3C-recommended mark-up structure for attributes that specify an element's timing behavior. Despite the context difference here, SMIL might generally indicate a useful approach for our present purpose. https://www.w3.org/TR/REC-smil/smil-timing.html
4. CAUSE: DOCUMENTING REASONS FOR CHANGE WITHIN XML DOCUMENT VERSION HISTORY
Changes to primary data in an invoice (in whole or in part) between a buyer and a seller due to the application of adjustments such as taxes, duties, price benchmarks, loyalty programs, conditional notifications, etc. must be efficiently documented. Essential data about change causality must be provided in a transformation record, and paired with the subsequent invoice version. At the users' option, the transformation record could be "adjacent to" or "intrinsic to" the invoice document.
4.1 DOCUMENTING THE CAUSE OF A CHANGE
Potentially, the cause of a change could be documented with reference to WHO, WHAT, WHEN, WHERE, WHY and HOW data:
- WHO: The identity (in a UBL way) of the change agent. In addition to the entity making the change, this might include the identity of an automated system acting on that entity's behalf.
- WHAT: Literally, the change.
- WHEN: Timestamp.
- WHERE: Location data of the change agent (IP address; URI; geodata).
- WHY: Reason(s) for the change. Depending on context, this could be a structured reference to an algorithm that's been applied, or a free form comment.
- HOW: Method used to make the change.
Caveat: We do not yet know if the following references bring far more complication than necessary, or if they indicate an elegant and pragmatic way to accommodate the inherent breadth of this requirement.
Nested Context Language (NCL 3.0) is a declarative language for hypermedia authoring that might provide a suitable XML Schema for documenting reasons for change. It was created in a different domain of application from UBL, but possibly the XML _expression_ requirement is similar: http://www.ncl.org.br/http://www.ncl.org.br/en/schemasxml#CausalConnectorhttp://www.ncl.org.br/en/schemasxml#NCL30CausalConnectorhttp://www.ncl.org.br/en/schemasxml#NCL30CausalConnectorFunctionality
Following are some excerpts from selected papers:
"It also presents how ... requirements could be offered in an XML-based language, in order to improve its expressiveness, presenting elements and attributes that could be incorporated in its DTD ... specifying n-ary relationships expressing causality or constraint among components." ... "In causal relationships, some action is executed when a specific condition is satisfied." ... "The action element represents actions that should be executed in the target end points of a causal link. They can be simple (simple-action) or compound (compound-action). Simple actions can be applied to end points that define presentation events (prepare, start, stop, pause, resume, abort) or to end points that define attribution events (relative-assign, absolute-assign, enable, disable, activate). Those values are defined through the action-name attribute of the simple-action element."
"In order to provide the necessary semantics for defining causal or constraint relationships among events, a hypermedia connector may be specialized in a causal or constraint connector. A causal hypermedia connector has two types of roles: condition and action. A constraint hypermedia connector has just one type of role, condition."
"This work focuses on the use of links for representing referential and synchronization relationships. The traditional referential relationship, usually represented by a link, can be considered a special case of a causal synchronization relationship, specifying that an action must be fired when a condition is satisfied. In this particular case, the triggering condition occurs at a non-deterministic time instant: the user selection of an anchor. Therefore, the definition of hypermedia links can be generalized to model other types of synchronization relationships"... "XConnector (17) is an XML-based language providing the definition of xconnector elements. Each xconnector defines a set of roles (that will be played by participating resources in a relationship) and how they actually interact, through a child element called glue."
"The final document generated after the template is processed will contain A, B and also synchronization links giving the sequential semantics."
4.2 DOCUMENTING THE SOURCE ALGORITHM USED IN A CHANGE
Caveat: These preliminary documentation requirements for computational algorithms in the e-commerce domain arise from work-in-progress by Xalgorithms Foundation.
Each externally-obtained algorithm that is invoked to alter data in a UBL document can be expressed with the following data elements:
- A uniform resource identifier (URI) of the source respository of the external algorithm (discovered, for example, through an IETF RfC 3375 and RfC 3401/3402 conformant registry), including ongoing version history of the algorithm
- A legal entity identifier (LEI, conformant with ISO 17442:2012) controlling the external algorithm ("control" is meant as specified in UNCITRAL Model Law on Electronic Transferable Records)
- A concise table-oriented _expression_ of the algorithm
Internet Engineering Task Force (IETF) References for the Xalgorithms Federated Registry
RfC 3375 “Generic Registry-Registrar Protocol Requirements” https://www.ietf.org/rfc/rfc3375.txt
RfC 3401 & 3402 “Dynamic Delegation Discovery System” http://www.rfc-base.org/rfc-3401.html http://www.rfc-base.org/rfc-3402.html
XML Signature WG https://www.w3.org/Signature/
"ISO 17442:2012 specifies the elements of an unambiguous legal entity identifier (LEI) scheme to identify the legal entities relevant to any financial transaction."
United Nations Conference on International Trade Law (UNCITRAL)http://www.uncitral.org/uncitral/en/commission/working_groups/4Electronic_Commerce.html
Software Package Data Exchange (SPDX) Specification\https://spdx.org/
, Xalgorithms Foundation