OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

ubl-lcsc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: [ubl-lcsc] Draft paper on instance creation guidelines


My apologies (again) for missing this discussion, so maybe i missed something, but I want to clarify some things about this thread.

I want to separate out two different issues involved here...

1. The need to create sample instances of 0p70 schemas - in a vanilla form, exactly compliant with the schemas given in the release with no extensions/customization.
These are the most important instances we need at this time.  We should not be concerned with any of this debate about modifying hybrids or contextualized implementations.  We need these to show how the basic 0p70 schemas work and also to have data to populate the forms using ken's stylesheets.  This was my first example of the Boeing Order (http://lists.oasis-open.org/archives/ubl-lcsc/200301/msg00211.html).  No additional namespace or elements are used.  As ken points out, this only populates 5 of the fields on his UN/Layout form - that is not a problem, as it is still a legitimate example.

2. The issue of how we can customize these schemas for additional components required by different contexts.  
This is what Sally's instances have been about and this is not going to be released in 0p70 on Feb 10th.  This is a more complex issue, and we don't know how we want to do this yet.  That is why we are debating it next week and hopefully have a position by release 1p00 in May - but we dont need a solution next week.  When I put together  my second example of the Boeing Order (http://lists.oasis-open.org/archives/ubl-lcsc/200301/msg00212.html), it was not to promote a solution, just to demonstrate the overall strategy for adding to the library with context-driven requirements.  My personal reaction to Ken's paper is that Option 3. semms the only sensible approach (i was just not familar enough with the technolgoy to do it that way).

I am concerned that we feel we cannot create meaningful  sample instances without resolving the issues in ken's paper.  The immediate requirements is not customized schemas and instances - it is 'standard' instances based on existing 0p70 schemas.

The meeting next week should spend time on Sally's examples and Ken's paper (issue 2).  This is part of the discussion on dealing with Context. But we shouldn't confuse that with the need to create straightfoward instances (issue 1).


G. Ken Holman wrote:
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.

.................. Ken



Draft Guidelines for UBL Instance Creation

Draft Guidelines for UBL Instance Creation

Author: G. Ken Holman
Date: $Date: 2003/01/31 17:18:19 $(UTC)

Copyright © 2003 OASIS

Table of contents

1 UBL Instance Creation Guidelines
1.1 Disclaimers (to be removed in final version of this document)
2 Perspective 1: UBL as a component resource
3 Perspective 2: UBL as an indivisible resource
4 Perspective 3: UBL as an extensible structure
5 Impact on processing applications
6 Impact on document validation

1: UBL Instance Creation Guidelines

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.

1.1: Disclaimers (to be removed in final version of this document)

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.

2: Perspective 1: UBL as a component resource

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>
  

3: Perspective 2: UBL as an indivisible resource

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>

4: Perspective 3: UBL as an extensible structure

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>
  

5: Impact on processing applications

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.

6: Impact on document validation

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

-- 
regards
tim mcgrath
fremantle  western australia 6160
phone: +618 93352228  fax: +618 93352142 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC