[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Latest version
-- Eduardo Gutentag | e-mail: eduardo.gutentag@Sun.COM Web Technologies and Standards | Phone: +1 510 550 4616 x31442 Sun Microsystems Inc. | 1800 Harrison St. Oakland, CA 94612 W3C AC Rep / OASIS TAB Chair
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article status="Working Draft">
<articleinfo>
<productname>wd-cmsc-cmguidelines-v01.3</productname>
<productnumber>03</productnumber>
<!--
<releaseinfo role="product"><ulink url="wd-spectools-docbook-template-03.xml">XML</ulink></releaseinfo>
<releaseinfo role="product"><ulink url="wd-spectools-docbook-template-03.html">HTML</ulink></releaseinfo>
<releaseinfo role="product"><ulink url="wd-spectools-docbook-template-03.pdf">PDF</ulink></releaseinfo>
<releaseinfo role="location">http://www.oasis-open.org/spectools/docs</releaseinfo>
-->
<title><replaceable>Guidelines For The Customization of UBL Schemas</replaceable></title>
<authorgroup>
<author>
<firstname><replaceable>Matthew</replaceable></firstname>
<surname><replaceable>Gertner</replaceable></surname>
<affiliation>
<address><email><replaceable>matthew@acepoint.cz</replaceable></email></address>
</affiliation>
</author>
<author>
<firstname>Eduardo</firstname>
<surname>Gutentag</surname>
<affiliation>
<orgname><replaceable>Sun Microsystems, Inc.</replaceable></orgname>
<address><email>eduardo.gutentag@sun.com</email></address>
</affiliation>
</author>
<collab>
<collabname>Arofan Gregory</collabname>
</collab>
<collab>
<collabname>Bill Burcham</collabname>
</collab>
</authorgroup>
<pubdate>04/04/03</pubdate>
<copyright>
<year>2003</year>
<holder>OASIS Open, Inc. All Rights Reserved.</holder>
</copyright>
<abstract>
<para><replaceable>This specification documents the naming and design
rules and guidelines for the construction of XML components for the UBL
vocabulary.</replaceable></para>
</abstract>
<legalnotice role="status">
<title>Status</title>
<para><replaceable>This is a draft document and is likely to change on a
weekly basis.</replaceable></para>
<para>If you are on the <email><replaceable>{xxx}</replaceable>@lists.oasis-open.org</email>
list for committee members, send comments there. If you are not on that
list, subscribe to the <email><replaceable>{xxx}</replaceable>-comment@lists.oasis-open.org</email>
list and send comments there. To subscribe, send an email message to
<email><replaceable>{xxx}</replaceable>-comment-request@lists.oasis-open.org</email>
with the word <quote><literal>subscribe</literal></quote> as the body of
the message.</para>
<para>For information on whether any patents have been disclosed that
may be essential to implementing this specification, and any offers of
patent licensing terms, please refer to the Intellectual Property Rights
section of the Security Services TC web page (<ulink
url="http://www.oasis-open.org/committees/security/">http://www.oasis-open.org/committees/security/</ulink>).</para>
</legalnotice>
</articleinfo>
<section id="s.introduction">
<title>Introduction</title>
<para>With the first public release of UBL, version 0p70, users can begin
to gain experience using the library in their applications for interchange
of business data among trading partners. Although the library will be
subject to change and extension as it approaches the final version, it
already contains important document types informed by the broad experience
of members of the UBL Technical committee, including EDI and XML experts.</para>
<para>One of the most important lesson learned from previous standards is
that no business library is sufficient for all purposes. Requirements
differ significantly amongst companies and industries, and a customization
mechanism is therefore needed in many cases before the document types can
be used in real-world applications. A primary motivation for moving from
the relatively inflexible EDI formats to a more robust XML approach is the
existence of formal mechanisms for performing this customization while
retaining maximum interoperability and validation.</para>
<para>In order for this interoperability and validation to be achieved,
care must be taken to adhere to strict guidelines when customizing UBL
document types. Although the UBL TC intends to produce a customization
mechanism that can be applied as an automatic process in the future, in
the meantime, and as part of this Phase I effort, the following guidelines
are offered.</para>
<para>This document aims to describe the procedure for customizing UBL,
with three distinct goals.</para>
<orderedlist>
<listitem>
<para>The first goal is to ensure that UBL users can extend UBL
schemas in a manner that:<itemizedlist><listitem><para>allows for
their particular needs,</para></listitem><listitem><para>can be
exchanged with trading partners whose requirements for data content
are different but related, and</para></listitem><listitem><para><emphasis
role="strong">is UBL compatible.</emphasis></para></listitem></itemizedlist></para>
</listitem>
<listitem>
<para>The second goal is to provide a couple of canonical escape
mechanisms for those whose needs extend beyond what the compatibility
guidelines can offer. Although the product of these escape mechanisms
cannot claim UBL compatibility, at least it can offer a clear
description of its relashionship to UBL, a claim that cannot be made
by other ad hoc methods.</para>
</listitem>
<listitem>
<para>The third goal is to gather use case data for the future UBL
context extension methodology, an automatic mechanism for creating
customized UBL schemas.</para>
</listitem>
</orderedlist>
</section>
<section id="background">
<title>Background</title>
<para>The major output of the UBL TC is encapsulated in the UBL Schemas.
It is assumed that in many cases users will need to customize these
schemas for their own use. In accordance with [ebXML] the UBL TC expects
this customization to be carried out only in response to contextual needs
(see [xxx]) and by the application of any one of the eight identified
context drivers and their possible values.</para>
<para>It must be noted that the UBL schemas themselves are the result of a
theoretical customization:</para>
<para>Behind every UBL Schema, an Ur-schema exists in which all elements
are optional and all types are abstract. As mandated in the XSD
specification, abstract types cannot be used as written; they can only be
used as a starting point for deriving new, concrete types. Ur-types are
modelled as abstract types since they are designed for derivation.</para>
<section>
<title>The UBL Schema</title>
<para>The first set of derivations from the abstract Ur-types is the UBL
Schema Library itself, which is assumed to be usable in 80% of business
cases. These derivations contain additional restrictions to reduce
ambiguity and provide a minimum set of requirements to enable
interoperable trading of data by the application of one context,
Business Process. The UBL schema may then be used by specific industry
organizations to create their own customized schemas. When the Schema is
used, conformance with UBL may be claimed. When a Schema that has been
customized through the UBL sanctioned derivation processs is used,
conformance with UBL may also be claimed.</para>
</section>
<section>
<title>Customization of UBL Schemas</title>
<para>It is assumed that in many cases specific businesses will use
customized UBL schemas. These customized schemas contain derivations of
the UBL types, created through additional restrictions and/or extensions
to fit more precisely the requirements of a given class of UBL users.
The customized UBL Schemas may then be used by specific organizations
within an industry to create their own customized schemas.</para>
</section>
<section id="custofcust">
<title>Customization of customization</title>
<para>Due to the extensiblilty of W3C Schema, this process can be
applied over and over to refine a set of schemas more and more
precisely, depending on the needs of specific data flows.</para>
<para>In other words, there is no theoretical limit to how many times a
Schema can be derived, leading to the possible equivalent of infinite
recursion. In order to avoid this, we have developed the Rule of
Once-per-Context, as presented later, in "<link
linkend="contextchains">Context Chains</link> " </para>
</section>
</section>
<section id="compatibility">
<title>Compatibility: Customization through Derivation</title>
<para>Central to the customization approach used by UBL is the notion of
schema derivation. This is based on object-oriented principles, the most
important of which are inheritance and polymorphism. The importance of the
latter can be gleaned from its linguistic origin: poly, meaning
"many", and morph, meaning "shape". By adhering to these
principles, document formats with different "shapes" can be used
interchangeably.</para>
<para>The UBL Naming and Design Rules Subcommittee (NDRSC) has decided to
use XSD, the standard XML schema language produced by the World Wide Web
Consortium (W3C), to model document formats. One of the most significant
advances of XSD over previous XML document description languages like DTDs
is that it has built-in mechanisms for handling inheritance and
polymorphism. It therefore fits well with the real-world requirements for
business data interchange and our goal of interoperability and validation.</para>
<para>There are three different scenarios (not all of which can be
accomplished through direct XSD derivation) in which derivations could be
performed on existing types:</para>
<itemizedlist>
<listitem>
<para>An existing UBL type fits the requirements for the application
with modifications supported by XSD derivation. These modifications
can include extension, adding new information to an existing type,
and/or refinement, restricting the set of information allowed to a
subset of that permitted by the existing type.</para>
</listitem>
<listitem>
<para>An existing UBL type is close to the requirements of the
application, but the changes needed go beyond those allowed directly
by XSD derivation. For example, the new type might need to broaden the
set of information allowed to a superset of that permitted by the
existing type.</para>
</listitem>
<listitem>
<para>No existing UBL type is found that can be used as the basis for
the new type. Nevertheless, the base library of core components that
underlies UBL can be used to build up the new type so as to ensure
that interoperability is at least possible on the core component
level.</para>
</listitem>
</itemizedlist>
<para>These Guidelines will deal with each of the above scenarios, but we
will first and foremost concentrate on the first, as it is the only one
that can produce UBL compatible schemas.</para>
<section>
<title>Use of XSD Derivation</title>
<para>XSD derivation allows for type extension and restriction. These
are the only means by which one can customize UBL schemas and claim UBL
compatibility. All other possible means, even if allowed by XSD itself,
are not allowed by UBL.</para>
</section>
<section>
<title>Extensions</title>
<para>XSD extension is used when additional information must be added to
an existing UBL type. For example, a company might use a special
identification code in relation to trading partners. This code should be
included in addition to the standard information used in a BuyerParty
description (AccountCode, PartyName, Address, etc.) when purchasing
goods. This can be achieved by creating a new type that references the
existing type and adds new the information:</para>
<programlisting> <xsd:complexType name="MyBuyerPartyType">
<xsd:extension base="cat:BuyerPartyType">
<xsd:element name="InternalSupplierCode" type="xsd:string"/>
</xsd:element>
</xsd:extension>
</xsd:complexType></programlisting>
<para>Some observations:</para>
<itemizedlist>
<listitem>
<para>Notice that derivation can be applied only to types and not to
elements that use those types. This is not a problem; UBL uses
explicit type definitions for all elements, in fact disallowing XSD
use of anonymous types that define a content model directly inside
an element declaration,</para>
</listitem>
<listitem>
<para>This derived type can be used anywhere the original type is
allowed. The instance document should use the xsi:type attribute to
indicate that a derived type is being used. This does not enforce
the use of the new type inside a given element, however, so in this
example Orders could still be created using the standard UBL
BuyerParty type. If the user wishes to require the use of the
derived type, a new derived type must be created from the Order type
using refinement and specifying that the MyBuyerPartyType is used.</para>
</listitem>
<listitem>
<para>UBL defines global elements for all types, and these elements,
rather than the types themselves, are used in aggregate element
declarations. It is therefore recommended that the same procedure be
used for derived types, so a MyBuyerParty element should be created
based on the MyBuyerPartyType.</para>
</listitem>
<listitem>
<para>All derived types should be created in a separate namespace
(which might be tied to the user organization) and reference the UBL
namespaces as appropriate.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Restrictions</title>
<para>In other cases, the user may wish to use the existing UBL type but
restrict the information in some way. This is accomplished through XSD
restriction. For instance, the UBL BuyerPartyType permits the inclusion
of any number of addresses or none. If a specific organization wishes to
allow exactly one address, this is achieved as follows (note that the
annotation fields are removed from the type definition to make the
example more readable):</para>
<programlisting><xsd:complexType name="MyBuyerPartyType">
<xsd:restriction base="cat:BuyerPartyType">
<xsd:sequence>
<xsd:element ref="ID" id="UBL000090">
</xsd:element>
<xsd:element ref="AccountCode" id="UBL000091" minOccurs="0">
</xsd:element>
<xsd:element ref="PartyName" id="UBL000092" minOccurs="0" maxOccurs="unbounded">
</xsd:element>
<xsd:element ref="Address" id="UBL000093" minOccurs="1" maxOccurs="1">
</xsd:element>
<xsd:element ref="PartyTaxScheme" id="UBL000094" minOccurs="0" maxOccurs="unbounded">
</xsd:element>
<xsd:element ref="BuyerContact" id="UBL000095" minOccurs="0">
</xsd:element>
</xsd:sequence>
</xsd:restriction>
</xsd:complexType></programlisting>
<para>Note that the entire content model of the base type, with the
appropriate changes must be repeated when performing restriction.</para>
</section>
</section>
<section id="contextanddocumentation">
<title>Compatibility: Context and Documentation</title>
<para>Every time a derivation is performed on an UBL- or UBL-derived
Schema, the context and the context value used must be documented. If this
is not done, then by definition the derived Schema is not UBL-compliant.</para>
<para>It is planned that a context extension methodology will be designed
to enable automatic customization of UBL types for specific purposes. This
methodology works by using a formal specification of the reasons for
customizing the type, known as the context. By expressing the context
formally and specifying rules for adapting types based on context, most of
the changes that need to be made to UBL in order for it to fit in a given
usage environment can be generated by the context engine rather than
performed manually. In addition, significant new flexibility can be
gained, since rules from two complementary contexts can be applied
simultaneously, yielding types appropriate for, say, the automobile
industry and the French geopolitical entity.</para>
<para>UBL has not yet progressed to this stage of development. For now,
one of the main goals of the UBL Context Methodology Subcommittee is to
gather as many use cases as possible to determined what types of
customizations are performed in the real world, and on what basis. Another
important goal is to ensure that types derived at this point from
UBL's version 1 can be still used in the future, intermixed with types
derived automatically in the future.</para>
<para>Context is expressed using a set of name/value pairs, where the
names are one of a limited set of context drivers established by the UBL
TC:</para>
<itemizedlist>
<listitem>
<para>Business process</para>
</listitem>
<listitem>
<para>Official constraints</para>
</listitem>
<listitem>
<para>Product classification</para>
</listitem>
<listitem>
<para>Business process role</para>
</listitem>
<listitem>
<para>Industry classification</para>
</listitem>
<listitem>
<para>Supporting role</para>
</listitem>
<listitem>
<para>Geopolitical</para>
</listitem>
<listitem>
<para>System capabilities</para>
</listitem>
</itemizedlist>
<para>Context should be included as an element Context (in the UBL
namespace) inside the documentation for each customized type, with the
name of the context derived expressed as in the list above, but using
capitalized camel case. The Context element has two attributes, driver and
value. For example, if the type is to be used in the French automobile
industry, the Context documentation would appear as follows:</para>
<programlisting><xsd:annotation>
<xsd:documentation>
<ubl:Context driver="IndustryClassification" value="Automotive"/>
<ubl:Context driver="Geopolitical" value="France"/>
</xsd:documentation>
<xsd:annotation></programlisting>
<para>If a customization is made that does not fit into any of the
existing context drivers, it should be described in prose form inside the
Context element:</para>
<programlisting format="linespecific"><xsd:annotation>
<xsd:documentation>
<ubl:Context>Used for jobs performed on weekends to specify additional data required by the trade union</ubl:Context>
</xsd:documentation>
<xsd:annotation></programlisting>
<note>
<para>Any issues with the set of context drivers currently defined or
the taxonomies to be used for specifying values should be communicated
to the UBL Context Driver Subcommittee.</para>
</note>
<section id="contextchains">
<title>Context chains</title>
<para>As mentioned in "<link linkend="custofcust">Customization of
Customization</link>", there is a risk that derivations may form
extremely long and unmanageable chains. In order to avoid this problem,
the Rule of Once-per-Context was formulated: no context can be applied,
at a given hierarchical level of that context, more than once in a chain
of derivations. </para>
</section>
</section>
<section>
<title>Customization through other means</title>
<para>There are two important types of customization that XSD derivation
does not allow. The first can be summarized as the deletion of required
components (that is, the reduction of a component's cardinality from
x..y to 0..y). The second is the ad hoc location of an addition to the
content model through extension. There may be some cases where the user
needs a different location for the addition, but XSD extension only allows
addition at the end of a sequence.</para>
<para>Because XSD derivation does not allow these types of customization,
any attempts at enabling them must by necessity produce results that are
not UBL compatible. However, in order to allow users to customize their
schemas in a UBL-friendly manner, the notion of an Ur-schema was invented:
for each UBL Schema, an Ur-schema exists in which all elements are
optional and all types are abstract. The use of abstract types is
necessary because Ur-types can never be used as is; a derived type must be
created, as per the definition of abstract types in the XSD specification.</para>
<section>
<title>Use of Ur-Types</title>
<para>XSD derivation is sufficient for most cases, but in some instances
it might be necessary to perform changes to the UBL types that are not
handled by standard mechanisms. In this case, the UBL Ur-types should be
used. Remember, an Ur-ype exists for each UBL standard type and differs
only in that all elements in the content model are optional, including
elements that are required in the standard type. By using the Ur-type,
the user can therefore make modifications, such as eliminating a
required field, that would not be possible using XSD derivation on the
standard type.</para>
<para>For instance, suppose an organization would like to use the UBL
BuyerPartyType, but does not want to use the required ID element. In
this case, normal XSD refinement is used, but on the ur type rather than
the standard type:</para>
<programlisting><xsd:complexType name="MyBuyerPartyType">
<xsd:restriction base="ur:BuyerPartyType">
<xsd:sequence>
<xsd:element ref="ID" id="UBL000090" minOccurs="0" maxOccurs="0">
</xsd:element>
<xsd:element ref="AccountCode" id="UBL000091" minOccurs="0">
</xsd:element>
<xsd:element ref="PartyName" id="UBL000092" minOccurs="0" maxOccurs="unbounded">
</xsd:element>
<xsd:element ref="Address" id="UBL000093" minOccurs="0" maxOccurs="unbounded">
</xsd:element>
<xsd:element ref="PartyTaxScheme" id="UBL000094" minOccurs="0" maxOccurs="unbounded">
</xsd:element>
<xsd:element ref="BuyerContact" id="UBL000095" minOccurs="0">
</xsd:element>
</xsd:sequence>
</xsd:restriction>
</xsd:complexType></programlisting>
<para>The new type is no longer compatible with the UBL BuyerPartyType,
so standard processing engines that know about XSD derivation will not
recognize the type relationship. However, some level of interoperability
is still preserved, since both UBL BuyerPartyType and MyBuyerPartyType
are derived from the BuyerPartyType Ur-type. If this additional
flexibility is required, a processor can be implemented to use the
Ur-type rather than the UBL type. It will then be able to process both
the UBL type and the custom type, since they have a common ancestor in
the Ur-type.</para>
<para>Once again, changes to the Ur-type do not enforce changes in the
enclosing type, so the UBL OrderType has to be changed as well if the
user organization wants to ensure that only the new MyBuyerPartyType is
used. In fact, the new OrderType will not be compatible with the UBL
OrderType, since MyBuyerPartyType is no longer derived from UBL
BuyerPartyType. However, the new OrderType can be derived from the
OrderType Ur-type to achieve maximum interoperability.</para>
<section>
<title>Building Types Using Core Components</title>
<para>Sometimes no type can be found in the UBL library or ur type
library that can be used as the basis of a new type. In this case, we
should still strive for maximum interoperability by building up the
new type using types from the core component library that underlies
UBL.</para>
<para>For example, suppose a user organization needs to include a
specialized product description inside business documents. This
description includes a unique ID, a name and the storage capacity of
the product expressed as an amount. The type definition should appear
as follows:</para>
<programlisting><xsd:complexType name="ProductDescriptionType">
<xsd:sequence>
<xsd:element name="ID" type="cct:IdentifierType"/>
<xsd:element name="Name" type="cct:TypeType"/>
<xsd:element name="Capacity" type="cct:AmountType"/>
</xsd:sequence>
</xsd:complexType></programlisting>
<para>It goes without saying that all new names defined when creating
custom types from scratch should also conform to the UBL Naming and
Design Rules.</para>
</section>
</section>
</section>
<appendix id="a.committee" role="non-normative">
<title>Committee Members</title>
<para>The following individuals were members of the committee during the
formulation of this document:</para>
<itemizedlist>
<listitem>
<para></para>
</listitem>
<listitem>
<para></para>
</listitem>
<listitem>
<para></para>
</listitem>
</itemizedlist>
</appendix>
<appendix id="a.notices">
<title>Notices</title>
<para>Copyright © The Organization for the Advancement of Structured
Information Standards [OASIS] 2001, 2002. All Rights Reserved.</para>
<para>OASIS takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to pertain to
the implementation or use of the technology described in this document or
the extent to which any license under such rights might or might not be
available; neither does it represent that it has made any effort to
identify any such rights. Information on OASIS's procedures with
respect to rights in OASIS specifications can be found at the OASIS
website. Copies of claims of rights made available for publication and any
assurances of licenses to be made available, or the result of an attempt
made to obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification, can be
obtained from the OASIS Executive Director.</para>
<para>OASIS invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary rights
which may cover technology that may be required to implement this
specification. Please address the information to the OASIS Executive
Director.</para>
<para>This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it or
assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are included
on all such copies and derivative works. However, this document itself may
not be modified in any way, such as by removing the copyright notice or
references to OASIS, except as needed for the purpose of developing OASIS
specifications, in which case the procedures for copyrights defined in the
OASIS Intellectual Property Rights document must be followed, or as
required to translate it into languages other than English.</para>
<para>The limited permissions granted above are perpetual and will not be
revoked by OASIS or its successors or assigns.</para>
<para>This document and the information contained herein is provided on an
<quote>AS IS</quote> basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</para>
<para>OASIS has been notified of intellectual property rights claimed in
regard to some or all of the contents of this specification. For more
information consult the online list of claimed rights.</para>
</appendix>
<appendix id="a.ipr">
<title>Intellectual Property Rights</title>
<para>For information on wether any patents have been disclosed that may
be essential to implementing this specification, and any offers of patent
licensing terms, please refer to the Intellectual Property Rights section
of the {technical-committee} web page (<ulink
url="http://www.oasis-open.org/committees/{technical-committee}"></ulink>)</para>
</appendix>
<appendix id="a.revhistory">
<title>Revision History</title>
<para><revhistory><revision><revnumber>03</revnumber><date>15 Aug 2002</date><authorinitials>ndw</authorinitials><revremark>Changed
copyright holder.</revremark></revision><revision><revnumber></revnumber><date></date></revision></revhistory></para>
</appendix>
<bibliography id="bibl">
<title>References</title>
<bibliodiv>
<title>Normative</title>
<bibliomixed id="rfc2119"><abbrev>RFC 2119</abbrev>S. Bradner.
<citetitle><ulink url="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119:
Key words for use in RFCs to Indicate Requirement Levels</ulink></citetitle>.
IETF (Internet Engineering Task Force). 1997.</bibliomixed>
</bibliodiv>
</bibliography>
</article>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]