[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [ubl-lcsc] Draft paper on instance creation guidelines
During the conference call today I was asked to summarize some of the technical discussions regarding sample instances in order to eventually become a formal committee guideline. It became obvious guidelines are needed when three different perspectives on how to create a sample instance were considered. Having only a single approach may not be an acceptable end position, but without some guidelines in place early, the effort put into creating example instances next week may be for naught. I hope the attached is found to be a useful starting point for the discussion. Thanks to Sally and Tim for creating the instances they did that were input into this document. .................. KenTitle: Draft Guidelines for UBL Instance Creation
Author: G. Ken Holman
Date: $Date: 2003/01/31 17:18:19 $(UTC)
Copyright © 2003 OASIS
The power and flexibility of the Universal Business Language (UBL) vocabularies can be seen quite differently by different users. This document promotes general guidelines for use of the UBL document models in the creation of instances to be processed by applications claiming to support UBL.
Three perspectives are captured in this draft document for consideration by the reader. As this document matures, probably only a single perspective will evolve as the guidelines for use. Certainly the historical contributions could be important annexes to help new readers understand that their own perspective (which might be one of the contributing views) had been considered, or more importantly, if it had not already been weighed and should be put forward to the committee for consideration.
This task was identified during the QA teleconference held 2003-01-31 14:30UTC.
At the request of the co-chair I've been asked to summarize three perspectives regarding creating UBL document instances. As an outsider to the group, I could very well have missed essential principles that have been decided by UBL committees in the past regarding the use of the UBL document models and reusable components, and for that I apologize that they are not included in the initial versions of this document.
Any misrepresentations of the different perspectives are my fault as I'm trying to capture what I thought I understood from the evidence at hand during the phone call.
Any bias to Perspective 3 that comes out of reading the document is unintentional because it is the perspective supported by the author; sorry about that. It is, however, what I conclude to be the best way to go.
In this perspective, all of the UBL constructs are available as a pool of information item descriptions for inclusion within an arbitrary structure of non-UBL content.
Consider the following example of an aerospace-oriented purchase order where the structure is largely governed by practices promoted by the Air Transport Association (ATA). Note how various UBL constructs are found throughout the instance.
<?xml version="1.0"?>
<ubl:Order.Detail xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="UBL-POsample-v0p1.xsd"
xmlns:ubl="urn:oasis:names:tc:ubl:Order:1.0:0.70"
xmlns:ccsd="ccsd-BoeingPOsampleV0p1.xsd">
<Header>
<ubl:Order.Buyer_Party>JA1</ubl:Order.Buyer_Party>
<ubl:Order.Seller_Party>81205</ubl:Order.Seller_Party>
<ccsd:OrderDocument.Processing.Code>4</ccsd:OrderDocument.Processing.Code>
<ccsd:OrderDocument.Type.Code>4</ccsd:OrderDocument.Type.Code>
<ccsd:OrderDocument.Purpose.Code>1</ccsd:OrderDocument.Purpose.Code>
<ubl:Order.Identifier>AWACS0001</ubl:Order.Identifier>
</Header>
<ccsd:LineItem>
<ccsd:SparePartItem.Manufacturer.Identifier>256T2800122</ccsd:SparePartItem.Manufacturer.Identifier>
<ccsd:LineItem.Ordered.Quantity>5</ccsd:LineItem.Ordered.Quantity>
<ccsd:BaseChargePrice.Quantity>EA</ccsd:BaseChargePrice.Quantity>
<ccsd:UnitChargePrice.Amount>100</ccsd:UnitChargePrice.Amount>
<ccsd:CustomerRequiredShipping.Date>20020701</ccsd:CustomerRequiredShipping.Date>
<ccsd:ShipmentDestinationLocation.Identifier>01</ccsd:ShipmentDestinationLocation.Identifier>
<ccsd:ManufacturerParty.Identifier>81205</ccsd:ManufacturerParty.Identifier>
<ccsd:OrderResponseProcessing.Priority.Code>AOG</ccsd:OrderResponseProcessing.Priority.Code>
<ccsd:AircraftEquipment.AviationAuthority.Identifier>N000001</ccsd:AircraftEquipment.AviationAuthority.Identifier>
<ubl:Order.Contract>JAPAN-AWACS-TEST</ubl:Order.Contract>
<ccsd:MiscelleanousInformation.Text>HOLD FOR PICKUP. NOTIFY JOHN DOE 253-773-1234 WHEN SHIPPED.
</ccsd:MiscelleanousInformation.Text>
</ccsd:LineItem>
</ubl:Order.Detail>
In this perspective, the UBL structure is inviolate and must reside wholly within any extended use or collection of non-UBL content.
Consider the following instance where the UBL Order is wholly contained within and wrapped by industry-specific constructs. While the UBL structure is preserved, there is no context for the industry information and no a priori knowledge to a processing application of where information can be found in the instance.
<?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSPY v5 U (http://www.xmlspy.com)--> <ao:AerospaceOrder xmlns:ao="urn:oasis:names:tc:ubl:examples:aerospace-industry:1.0:0.70" xmlns:cat="urn:oasis:names:tc:ubl:CommonAggregateTypes:1.0:0.70" xmlns:cct="urn:oasis:names:tc:ubl:CoreComponentTypes:1.0:0.70" xmlns:ccts="urn:oasis:names:tc:ubl:CoreComponentParameters:1.0:0.70" xmlns:po="urn:oasis:names:tc:ubl:Order:1.0:0.70" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:ubl:examples:aerospace-industry:1.0:0.70 C:\xml\ubl\0p70\packaging\0p70\xsd\AircraftIndustyContext.xsd"> <po:Order> <cat:ID>AWACS0001</cat:ID> <IssueDate>AWACS0001</IssueDate> <cat:BuyerParty> <cat:ID>JA1</cat:ID> </cat:BuyerParty> <cat:SellerParty> <cat:ID>81205</cat:ID> </cat:SellerParty> <cat:SalesConditions> <!-- ccsd:OrderResponseProcessing.Priority.Code --> <cat:ConditionID></cat:ConditionID> <cat:ActionCode>AOG</cat:ActionCode> </cat:SalesConditions> <cat:DeliveryTerms> <cat:ID>1</cat:ID> <cat:SpecialTerms>HOLD FOR PICKUP. NOTIFY JOHN DOE 253-773-1234 WHEN SHIPPED. </cat:SpecialTerms> </cat:DeliveryTerms> <cat:OrderLine> <cat:BuyersID/> <cat:Quantity unitCode="EA">5</cat:Quantity> <cat:Item> <cat:ID></cat:ID> <cat:ManufacturersItemIdentification> <cat:ID schemeAgencyID="81205">256T2800122</cat:ID> <!-- using the schemaAgencyID for the Manufacturer's ID --> </cat:ManufacturersItemIdentification> <cat:BasePrice> <cat:PriceAmount currencyID="USD">100</cat:PriceAmount> </cat:BasePrice> </cat:Item> <cat:DeliveryRequirement> <cat:ID></cat:ID> <cat:DeliverToAddress> <cat:ID>01</cat:ID> </cat:DeliverToAddress> </cat:DeliveryRequirement> <cat:OrderedShipment> <cat:ID></cat:ID> <cat:ShipmentStage> <cat:StageID></cat:StageID> <cat:TransitPeriod> <cat:StartDateTimeDate>2002-07-01</cat:StartDateTimeDate> <!-- This is for complex because it is the required shipping date - not the required delivery date --> </cat:TransitPeriod> </cat:ShipmentStage> </cat:OrderedShipment> </cat:OrderLine> <cat:Contract> <cat:ID>JAPAN-AWACS-TEST</cat:ID> </cat:Contract> </po:Order> <!-- using separate namespace extension to define industry elements --> <ao:AircraftEquipment> <ao:AviationAuthority> <cat:ID>N000001</cat:ID> </ao:AviationAuthority> </ao:AircraftEquipment> </ao:AerospaceOrder>
In this perspective, the UBL structure is preserved but not inviolate in that non-UBL content is allowed to be interleaved throughout the governing UBL structure.
Consider the following instance where the governing structure is a UBL order. This simple example doesn't have a lot of industry-specific information, but what is there is collected at the end of the instance. The instance could very well have other industry-specific information peppered through the content at different places in the document, provided any UBL content is not found as a descendant of any industry-specific content.
<?xml version="1.0" encoding="UTF-8"?> <po:Order xmlns:ao="urn:oasis:names:tc:ubl:examples:aerospace-industry:1.0:0.70" xmlns:cat="urn:oasis:names:tc:ubl:CommonAggregateTypes:1.0:0.70" xmlns:cct="urn:oasis:names:tc:ubl:CoreComponentTypes:1.0:0.70" xmlns:ccts="urn:oasis:names:tc:ubl:CoreComponentParameters:1.0:0.70" xmlns:po="urn:oasis:names:tc:ubl:Order:1.0:0.70" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:ubl:examples:aerospace-industry:1.0:0.70 C:\xml\ubl\0p70\packaging\0p70\xsd\AircraftIndustyContext.xsd"> <cat:ID>AWACS0001</cat:ID> <IssueDate>AWACS0001</IssueDate> <cat:BuyerParty> <cat:ID>JA1</cat:ID> </cat:BuyerParty> <cat:SellerParty> <cat:ID>81205</cat:ID> </cat:SellerParty> <cat:SalesConditions> <!-- ccsd:OrderResponseProcessing.Priority.Code --> <cat:ConditionID></cat:ConditionID> <cat:ActionCode>AOG</cat:ActionCode> </cat:SalesConditions> <cat:DeliveryTerms> <cat:ID>1</cat:ID> <cat:SpecialTerms>HOLD FOR PICKUP. NOTIFY JOHN DOE 253-773-1234 WHEN SHIPPED. </cat:SpecialTerms> </cat:DeliveryTerms> <cat:OrderLine> <cat:BuyersID/> <cat:Quantity unitCode="EA">5</cat:Quantity> <cat:Item> <cat:ID></cat:ID> <cat:ManufacturersItemIdentification> <cat:ID schemeAgencyID="81205">256T2800122</cat:ID> <!-- using the schemaAgencyID for the Manufacturer's ID --> </cat:ManufacturersItemIdentification> <cat:BasePrice> <cat:PriceAmount currencyID="USD">100</cat:PriceAmount> </cat:BasePrice> </cat:Item> <cat:DeliveryRequirement> <cat:ID></cat:ID> <cat:DeliverToAddress> <cat:ID>01</cat:ID> </cat:DeliverToAddress> </cat:DeliveryRequirement> <cat:OrderedShipment> <cat:ID></cat:ID> <cat:ShipmentStage> <cat:StageID></cat:StageID> <cat:TransitPeriod> <cat:StartDateTimeDate>2002-07-01</cat:StartDateTimeDate> <!-- This is for complex because it is the required shipping date - not the required delivery date --> </cat:TransitPeriod> </cat:ShipmentStage> </cat:OrderedShipment> </cat:OrderLine> <cat:Contract> <cat:ID>JAPAN-AWACS-TEST</cat:ID> </cat:Contract> <ao:AircraftEquipment> <ao:AviationAuthority> <cat:ID>N000001</cat:ID> </ao:AviationAuthority> </ao:AircraftEquipment> </po:Order>
The perspective of many processing applications is to address information using the XML Path Language (XPath) as both relative and absolute addresses of nested elements in a tree structure to find desired constructs.
For example, the unit price of each line item found at the absolute address /po:Order/cat:OrderLine is found at the relative address cat:Item/cat:BasePrice/cat:PriceAmount. The invoice total is found at the absolute address /po:Order/po:LineExtensionTotalAmount.
Moving the UBL document element inside another instance breaks the absolute XPath addresses (though not the relative addresses), requiring the processing application to hunt down the document element before beginning processing. Not having any context with which to process industry specific constructs may make the processing too complex to be viable, and would break the XML "model" of hierarchical processing.
Specialization of processing applications can be done in a straightforward fashion when using technologies such as stylesheets. For example, a "push-oriented" XSLT stylesheet designed to access a UBL structure can be tailored through the use of xsl:import to override a part of the UBL structure to accommodate expected industry-specific constructs without destabilizing the processing of the remainder of the document.
Perspective 3, therefore, presents the least amount of impact on a processing application. Those constructs known to the processing application are found where they are expected, addressed from the top of the document. Processing can be designed to tolerate the presence of all foreign constructs and to accommodate extended processing needs where necessary.
Perspective 2 might be considered a close second after accommodating the finding of the UBL document element and the sacrificing of context for the industry-specific content.
This draft of the document does not address instance validation issues, only instance processing issues.
Specializing an instance will require specializing the document model against which the instance is validated. Where supplemental industry-specific information need not be validated, consideration could be given to the writing of the UBL models to explicitly allow any foreign content.
A validation strategy that is often available is to strip constructs from a combined instance into individual instances of only a single vocabulary to then be validated separately and considered in the evaluation of the whole.
Draft Guidelines for UBL Instance Creation
G. Ken Holman
Copyright © 2003 OASIS
$Date: 2003/01/31 17:18:19 $(UTC)
-- Upcoming hands-on in-depth Europe: February 17-21, 2003 XSLT/XPath and/or XSL-FO North America: June 16-20, 2003 G. Ken Holman mailto:gkholman@CraneSoftwrights.com Crane Softwrights Ltd. http://www.CraneSoftwrights.com/o/ Box 266, Kars, Ontario CANADA K0A-2E0 +1(613)489-0999 (F:-0995) ISBN 0-13-065196-6 Definitive XSLT and XPath ISBN 0-13-140374-5 Definitive XSL-FO ISBN 1-894049-08-X Practical Transformation Using XSLT and XPath ISBN 1-894049-10-1 Practical Formatting Using XSL-FO Male Breast Cancer Awareness http://www.CraneSoftwrights.com/o/bc
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC