[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Schema Changes and Related Questions to the TC
UBL TC, Greetings. I was tasked at the last Atlantic TC call with using the updated NDR document from the McLean face-to-face along with the minutes of the last Atlantic TC call to bring together a list of Schema Change Requirements for perusal by the SSC and for agreement by the TC prior to their being passed to David for action. Please find and consider for this purpose the attached file called "First Set of Schema Changes Required for UBL 1-1 (draft 1).txt". During this task I came across some ambiguities for which I think we would need clarification, perhaps leading to further Schema change requirements (I would suggest, for the next deadline for such changes). I have listed these in the attached file called "Clarifications Requested for First Set Schema Changes.txt". Please would the TC consider these queries too. An important need for further NDR review (and other technical discussion) relates to the derivation requirements in rules VER8 and VER9. As a possible aid to further this discussion I have created a set of three prototype Schemas which I've packaged together with imported (directly and indirectly) UBL 1.0 Schemas and these are attached as zipped (extension renamed) file "xsd-derivation-1-1-prototype-2.zzz" together with a list of changes which would minimally, I believe, be necessary to Schemas to implement these called "Prototype of derivation 2.txt". The latter file contains a list (at the end) of suggested points for NDR and TC consideration. A particular outcome of this excercise was the realisation that it might be that only some of the Schemas (CAC, CBC, documents and possibly some codelists) and not all (e.g. not necessarily UDT, CCT, CCParams) would need changing in UBL 1.1. UBL 1.0 would potentially provide the other Schemas unchanged as indirect imports. This may have a bearing on how the existing and changed NDR rules are to be implemented, particularly affecting the view of the updated rules relating to the UDT Schema and CCT Schema. Special consideration might be required separately of how codelist updates should be implemented within this design. * ----------------------------------------------------------------------------------------- The most pressing of the attached documents may be the set of Schema change requirements "First Set of Schema Changes Required for UBL 1-1 (draft 1).txt" as for these there was the deadline of today. However some aspects of the other matters may affect the decision whether to agree these changes and the appropriateness or otherwise of implementing these changes first, as planned. * ----------------------------------------------------------------------------------------- Unfortunately it wasn't possible for the SSC to consider these matters other than the GXS1, VER8 and VER9 rules at the last meeting so it would seem best in keeping with the schedule for these to be agreed (or otherwise) by the TC first. Then the agreed changes can be both passed to David and simultaneously, perhaps, looked at by the SSC. Many thanks All the best Stephen Green
First Specification of Schema Changes Required for UBL Version 1.1 (1st March 2005)
------------------------------------------------------------------------------------
NOTES
Some NDR 1.1 changes which DO NOT require changes to the Schemas
are noted here:
N1. Changes to the rules defining the identifiers in the document name section
of each of the common Schema headers leave the identifiers used in UBL 1.0
common Schemas unchanged, e.g. 'CommonAggregateComponents' (Rule SSM10),
'CommonBasicComponents' (Rule SSM12), etc.
N2. GSX6 does not appear to require any changes to Schemas. It now states
"The xsd:final attribute MUST be used to control extensions where there is
a desire to prohibit further extensions"
QUERIES
Some NDR 1.1 changes appear to require changes which might break backwards
compatibility and so clarification is being sought of these from the TC.
These have been forwarded along with other queries as a separate document to the TC
Further rules are also sought from the TC to clarify such issues as how the VER8 and
VER9 rules impact on rule GXS1 (concerning details of layout).
Answers to these queries may form part of a second submission of Schema changes
requested later in the year.
The changes below are those thought to be unambiguous from the change requirements
received before the first deadline set as 1st March 2005.
CHANGE REQUIREMENTS (1st March 2005)
Schema changes required by NDR version 1.1 work in McLean Feb 2005
(note that this list excludes for the timebeing a possible further set
of codelist Schema change requirements):
C1. Changes to Rule DOC8 now states the following:
"The xsd:documentation element for every Supplementary Component
attribute declarationType MUST contain a structured set of annotations in the
following sequence and pattern:
• Name (mandatory): Name in the Registry of a Supplementary Component of
a Core Component Type.
• Definition (mandatory): A clear, unambiguous and complete explanation of
the meaning of a Supplementary Component and its revlevance for the related
Core Component Type.
• Primitive type (mandatory): PrimitiveType to be used for the representation
of the value of a Supplementary Component.
• Possible Value(s) (optional): one possible value of a Supplementary
Component."
This requires the addition of xsd:documentation to every Supplementary
Component attribute where it is declared in the common Schemas (CCT, UDT and SDT)
and codelist Schemas
C2. New Rule DOC9 in addition to change C1 above states the following:
"The xsd:documentation element for every Supplementary Component
attribute declaration containing restrictions MUST include the following
additional information appended to the information required by DOC8:
• Restriction Value(s) (mandatory): The actual value(s) that is (are) valid for
the Supplementary Component."
This requires further xsd:documentation for Supplementary Components attribute
declarations which contain restrictions
C3. New Rule CTD20 states:
"For every property identified in the UBL model a named XSD:ComplexType
must be defined"
This may perhaps mean the creation of new complex types but see C4 below.
Schema changes required by NDR version 1.0 and version 1.1 due to UBL 1.1
being a minor release
C4. All versioning rules, though unchanged from NDR 1.0, may apply differently
to UBL 1.1 Schemas compared with 1.0 Schemas but special attention is drawn to
rules VER8 and VER9 which are expected to have a major impact on 1.1 Schema
generation. These state:
"[VER8] A UBL minor version document schema MUST import its immediately preceding
version document schema.
[VER9] UBL Schema and schema module minor version changes MUST be limited to the
use of xsd:extension or xsd:restriction to alter existing types or add new constructs."
This clearly implies that some additional mechanism is required to be employed
in Schema generation for UBL 1.1 (and any subsequent minor versions) in which
comparison is made with the previous version.
[see Query Q7 in separate query document]
Special Changes made to rule GXS1 during TC Atlantic Call 23rd Feb 2005, though
requiring a later review in line with C4 and query Q7 above, require the following
Schema layout (which would need to be fitted later with C4 details once these
are provided):
C5. 1.1 Schema layout required by the currently amended rule GSX1
with added agreements/comments in square brackets and
with a), b), etc denoting subsections for clarity
[GXS1]
UBL Schema MUST conform to the following physical layout as applicable:
a)
XML Declaration
i.e. <?xml version="1.0" encoding="UTF-8"?>
b)
Schemas should include comment section separator.
<!-- ===== Copyright Notice ===== -->
c)
Required OASIS full copyright notice.
"Copyright ? 2001-2004 The Organization for the Advancement of Structured
Information Standards (OASIS). All rights reserved.
Copyright text should be taken verbatim from OASIS:
http://www.oasis-open.org/who/ipr/intellectual_property_2000-1-13.php
section OASIS.IPR.4.Notices, subsections (A), (B), (C), and,
when applicable, subsection (D).
(This is a new ipr policy for OASIS and takes effect on 15 April 2005.)
d)
In addition, the following fields should be included in the header comment,
below the copyright:
OASIS Open (http://www.oasis-open.org/)
Universal Business Language Specification
(http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl)
Document Name: <insert document name w/o suffix>
Generated On: <insert date with timestamp>
e)
They should be clearly separated from the copyright notice.
A single dashed line should be used as the separator.
f)
<!-- ===== xsd:schema Element With Namespaces Declarations ===== -->
Schemas need to be updated to include this comment line.
g)
xsd:schema element to include version attribute and namespace declarations in
the following order:
xmlns:xsd
[Schemas already conform with above line.]
Target namespace
Default namespace
CommonAggregateComponents
CommonBasicComponents
CoreComponentTypes
Unspecialized Datatypes
Specialized Datatypes
Identifier Schemes
Code Lists
[Schemas currently don't conform to this order.
Order needs review for technical issues, but otherwise is fine as in rule.
Schemas need to be updated to conform to this order (unless technical
reason for altering the order).]
[NOTE: Not all schemas need to include all the following declarations.
'As applicable', in the opening sentence
of the rule, means these can be present or not present, as needed, as long
as they are in this order. This applies to several of the following cases]
h)
Attribute Declarations:
elementFormDefault="qualified"
attributeFormDefault="unqualified"
[schemas currently conform to the two lines above.]
i)
<!-- ===== Imports ===== -->
[Schemas do not have this comment line.
Add this to schemas (unless there are no imports)]
j)
CommonAggregateComponents schema module
CommonBasicComponents schema module
Unspecialized Types schema module
Specialized Types schema module
[Schemas don't currently conform to this order.
Change schemas to conform to this order unless
technically problematic or non-standard. Some
have added that the order is only important
for the sake of specification of some order
and note that there is no other technical
requirement to adhere to any particular order so
if for some technical reason the order cannot
be maintained in generation that is understood.]
k)
[There will be further discussion later about specifying
in the Rule the following which are currently already included
by the Schema generator
- any codelist schemas
- cc parameters schema]
l)
<!-- ===== Global Attributes ===== -->
Global Attributes and Attribute Groups
[The Schemas already conform to this.
Add global attribute or attribute groups here,
and add comment section separator when they are present.]
m)
<!-- ===== Root Element ===== -->
Root Element Declaration
Root Element Type Definition
[This is how it is now in schemas,
but schemas need to add comment section separator.]
n)
<!-- ===== Element Declarations ===== -->
alphabetized order
[This is how it is now in schemas,
but schemas need to add comment section separator.]
[Further discussion will consider the following additions to the rule
about setting the alphabetical order: ignore case
(i.e., fold case), and ignore the xsd-related suffix "type" when
it's there purely for xsd reasons.]
o)
<!-- ===== Type Definitions ===== -->
All type definitions segregated by basic and aggregates as follows
[Schemas should add comment section separator.]
p)
<!-- ===== Aggregate Business Information Entity Type Definitions ===== -->
alphabetized order of AggregateBusinessInformationEntity TypeDefinitions
[Schemas should include comment section separator if section has content.]
q)
<!-- =====Basic Business Information Entity Type Definitions ===== -->
alphabetized order of BasicBusinessInformationEntities
[Schemas should include comment section separator if section has content.]
[Note: there still needs to be review of the Parameters (CCTS) Schema and
the above may need revision for codelist Schemas depending on the outcome
of codelist Schema design decisions. Further changes may be required to
conform to VER8 and VER9 too.]
----------------------------------------------------------------------------------------
An Illustration to Aid in discussion of NDR Rules and Schema Generator Design for use of
Derivation in adding new BIEs to UBL minor versions (here a prototypic 1.1 version)
----------------------------------------------------------------------------------------
Author: Stephen D.Green
Date: Feb 28th 2005
----------------------------------------------------------------------------------------
These notes are to accompany a set of Schemas (prototype-2) illustrating a simple use of xsd derivation to
implement NDR rules VER8 and VER9 in a minor version prototype of UBL. The illustration involves
the minimalistic case of the addition of a single BBIE to an Invoice both at Document level and at line
level. No other changes are made other than those necessary to the Invoice Document, Common Aggregate Component
and Common Basic Component Schemas.
The three new Schemas are held in the folders (for illustration called common-prototype-2 and maindoc-prototype-2)
and all other Schemas are imported from the 1.0 folders. This may well be an over-simplification and it might
be decided that all Schemas should be updated to the new version (e.g. 1.1) but both the directly and all the
indirectly imported Schemas (almost all previous version Schemas) would still have to be provided in the package.
The following are the additions to Schemas that were found to be necessary for this minimal derivation mechanism.
Invoice Schema showing a new BBIE (InspectionDate as an example) at Document level in the Invoice Document
----------------------------------------------------------------------------------------------------------
...
xmlns="urn:oasis:names:prototype:ubl:schema:xsd:Invoice-1.1" xmlns:in10="urn:oasis:names:specification:ubl:schema:xsd:Invoice-1.0"
...
xmlns:cbc="urn:oasis:names:prototype:ubl:schema:xsd:CommonBasicComponents-1.1" xmlns:cac="urn:oasis:names:prototype:ubl:schema:xsd:CommonAggregateComponents-1.1"
...
targetNamespace="urn:oasis:names:prototype:ubl:schema:xsd:Invoice-1.1"
...
<xsd:import namespace="urn:oasis:names:specification:ubl:schema:xsd:Invoice-1.0" schemaLocation="../maindoc/UBL-Invoice-1.0.xsd"/>
...
<xsd:import namespace="urn:oasis:names:prototype:ubl:schema:xsd:CommonBasicComponents-1.1" schemaLocation="../common-prototype-2/UBL-CommonBasicComponents-1.1-prototype-2.xsd"/>
<xsd:import namespace="urn:oasis:names:prototype:ubl:schema:xsd:CommonAggregateComponents-1.1" schemaLocation="../common-prototype-2/UBL-CommonAggregateComponents-1.1-prototype-2.xsd"/>
...
<xsd:complexType name="InvoiceType">
<xsd:annotation>
<xsd:documentation>
<ccts:Component>
<ccts:ComponentType>ABIE</ccts:ComponentType>
<ccts:DictionaryEntryName>Invoice. Details</ccts:DictionaryEntryName>
<ccts:Version>1.1</ccts:Version>
<ccts:Definition>the document that describes the finanical commitment of the Order</ccts:Definition>
<ccts:ObjectClass>Invoice</ccts:ObjectClass>
</ccts:Component>
</xsd:documentation>
</xsd:annotation>
<xsd:complexContent>
<xsd:extension base="in10:InvoiceType">
<xsd:sequence>
<xsd:element ref="InspectionDate" minOccurs="0" maxOccurs="1" >
<xsd:annotation>
<xsd:documentation>
<ccts:Component>
<ccts:ComponentType>BBIE</ccts:ComponentType>
<ccts:DictionaryEntryName>Invoice. Inspection Date. Date</ccts:DictionaryEntryName>
<ccts:Definition>..[an additional BIE for illustrating a prototype of derivation]..</ccts:Definition>
<ccts:Cardinality>0..1</ccts:Cardinality>
<ccts:ObjectClass>Invoice</ccts:ObjectClass>
<ccts:PropertyTerm>Inspection Date</ccts:PropertyTerm>
<ccts:RepresentationTerm>Date</ccts:RepresentationTerm>
<ccts:DataType>Date_Date Time. Type</ccts:DataType>
</ccts:Component>
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="InspectionDate" type="cbc:InspectionDateType"/>
Common Aggregate Schema showing a new BBIE (InspectionDate as an example ) at ABIE level in the InvoiceLine
-----------------------------------------------------------------------------------------------------------
...
xmlns="urn:oasis:names:prototype:ubl:schema:xsd:CommonAggregateComponents-1.1"
xmlns:cac10="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-1.0"
...
targetNamespace="urn:oasis:names:prototype:ubl:schema:xsd:CommonAggregateComponents-1.1"
...
<xsd:complexType name="InvoiceLineType">
<xsd:annotation>
<xsd:documentation>
<ccts:Component>
<ccts:ComponentType>ABIE</ccts:ComponentType>
<ccts:DictionaryEntryName>Invoice Line. Details</ccts:DictionaryEntryName>
<ccts:Version>1.1</ccts:Version>
<ccts:Definition>information directly relating to a line item of a transaction. It identifies the item but only includes details about the item that are pertinent to one occurrence on a line item, e.g. quantity etc.</ccts:Definition>
<ccts:ObjectClass>Invoice Line</ccts:ObjectClass>
</ccts:Component>
</xsd:documentation>
</xsd:annotation>
<xsd:complexContent>
<xsd:extension base="cac10:InvoiceLineType">
<xsd:sequence>
<xsd:element ref="cbc:InspectionDate" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>
<ccts:Component>
<ccts:ComponentType>BBIE</ccts:ComponentType>
<ccts:DictionaryEntryName>Invoice. Inspection Date. Date</ccts:DictionaryEntryName>
<ccts:Definition>..[an additional BIE for illustrating a prototype of derivation]..</ccts:Definition>
<ccts:Cardinality>0..1</ccts:Cardinality>
<ccts:ObjectClass>Invoice</ccts:ObjectClass>
<ccts:PropertyTerm>Inspection Date</ccts:PropertyTerm>
<ccts:RepresentationTerm>Date</ccts:RepresentationTerm>
<ccts:DataType>Date_Date Time. Type</ccts:DataType>
</ccts:Component>
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
...
Common Basic Schema showing a new BBIE (at ABIE level in the InvoiceLine in the CAC Schema)
-------------------------------------------------------------------------------------------
...
xmlns="urn:oasis:names:prototype:ubl:schema:xsd:CommonBasicComponents-1.1"
...
targetNamespace="urn:oasis:names:prototype:ubl:schema:xsd:CommonBasicComponents-1.1"
...
<xsd:element name="InspectionDate" type="InspectionDateType"/>
...
<xsd:complexType name="InspectionDateType">
<xsd:simpleContent>
<xsd:extension base="udt:DateType"/>
</xsd:simpleContent>
</xsd:complexType>
...
Comments and Observations
-------------------------
1. No 1.1 changes to NDR rules are shown here, only derivation VER8 and VER9 concepts and a possible use of
ccts:Version in the documentation
2. Matters for NDR consideration might include
a) - a rule for the the prefix naming convention to be used for imported Schema namespaces
b) - clarification of the methods for documentation when derivation is invloved
c) - an update to rule GXS1
d) - further complexity may result in problems if Schemas other than those above (e.g. codelist Schemas) are changed
3. There appears to be an error in the CM documentation in that both xsd:complexContent and xsd:sequence
are omitted in the extension example
4. Modeling issues arise from the need to add new BIEs only at the end of existing sequences (as was
emphasised in earlier 'containership discussions')
5. Illustrations of any resulting need to use xsi:type in instances may warrant further instance examples
for UBL 1.1
Queries Regarding Schema Changes for UBL version 1.1 (Feb 2005) ---------------------------------------------------- A. Backwards Compatibility Queries Some NDR 1.1 changes appear to require changes which might break backwards compatibility and so clarification is sought of these from the TC. These are: Q1. Rule GNR10 has been added which reads "Acronyms and abbreviations at the beginning of an attribute declaration MUST appear in all lower case. All other acronym and abbreviation usage in an attribute declaration must appear in upper case." This would appear to require the following change to the 1.0 common Schemas: Change of the attribute "URI" of the CCT BinaryType to all lower case "uri". Although this has no bearing on actual UBL 1.0 documents since these do not use this CCT, backwards compatibility for customized versions (including new documents created using the customization methodology) might use the BinaryType CCT and therefore loose backwards compatibility if converted to UBL 1.1 were this change implemented in the UBL 1.1 Schemas and in Edifix. Q2. Rule GNR11 has been added which reads "Acronyms MUST appear in all upper case for all element declarations and type definitions." If this rule were to require the renaming of any existing 1.0 elements this too would break backwards compatibility of instances in 1.1 with 1.0. Q3. Rule ATN2 states "If the object class of the supplementary component dictionary entry name contains the name of the representation term of the parent CCT, the duplicated object class word or words MUST be removed from the supplementary component xsd:attribute name." Q4. Rule ATN2 now states: "If the object class of the supplementary component dictionary entry name contains the name of the representation term of the parent CCT, the duplicated object class word or words MUST be removed from the supplementary component xsd:attribute name." If this new rule were to require Schema changes then these might break backwards compatibility. Would the TC confirm whether Schema changes should be made according to this rule or not. This may relate to clarification requested from the SSC regarding naming in general where it was again assumed that no actual name changes would be either required or (where backwards compatibility might be affected) allowed. B. Other Queries Q5. Rules CTD7 to CTD12 are accompanied by explanatory text in the NDR document which is changed in 1.1 to include the clarifying term "uses xsd:base" in parentheses, as follows: "5.1.3.13.1 Unspecialized Datatypes The ccts:UnspecializedDatatypes reflect the instantiation of the ccts:Core ComponentTypes. Each ccts:UnspecializedDatatype declaration is based on (uses xsd:base) its corresponding qualified ccts:CoreComponentType and represents either a primary or secondary representation term. " In particular Rule CTD10 states "Every unspecialized Datatype that represents a secondary representation term whose corresponding ccts:CCT is defined as an xsd:simpleType MUST also be defined as an xsd:simpleType and MUST be based on the same xsd:simpleType." This would appear to require that the UDT Schema's datatype declarations for simpleType dataypes use the corresponding CCT as their xsd:base rather than an xsd:dataype (as used in 1.0). This would require changes to the UDT Schema (to the simpleTypes) but clarification of this is sought from the TC. The combination of the NDR text "Each ccts:UnspecializedDatatype declaration is based on (uses xsd:base) its corresponding qualified ccts:CoreComponentType" and the "...and MUST be based on the same xsd:simpleType..." in the Rule CTD10 means that it isn't quite clear whether the simpleType UDTs should be have as xsd:base the corresponding cct:datatype or the xsd:datatype. Clarification is sought again over the UDT DateType which requires use of the xsd:date and cannot use as xsd:base the cct:DateTimeType nor the datatype xsd:dateTime (which the CCT DateTimeType uses). How does this rule apply? Q6. Similar to Q5 above, rule CTD12 states "The unspecialized Primary Representation Term Datatype xsd:complexType definition xsd:simpleContent element must contain one xsd:restriction element with an xsd:base attribute whose value is equal to the corresponding cct:ComplexType" Clarification in line with Q5 is sought here since it is rather ambiguous as to whether the UDT based on a CCT should use the same xsd:dataype as its xsd:base as the corresponding CCT uses or whether as its base it should use the cct:datatype itself? e.g. should the UDT Name have xsd:base='xsd:string' or xsd:base='cct:TextType' (cct:TextType having xsd:base='xsd:string')? Q7. Rules VER8 and VER9 which are expected to have a major impact on 1.1 Schema generation. These state: [VER8] A UBL minor version document schema MUST import its immediately preceding version document schema. [VER9] UBL Schema and schema module minor version changes MUST be limited to the use of xsd:extension or xsd:restriction to alter existing types or add new constructs. This clearly implies that some additional mechanism is required to be employed in Schema generation for UBL 1.1 (and any subsequent minor versions) in which comparison is made with the previous version. Further rules are sought from the TC to clarify such issues as which namespaces are to be used for imports, 'tc' or 'specification' and as defining the 'previous version' and how this rule impacts, as expected, on rule GXS1 (concerning details of layout).
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]