further design considerations for 2.0 (prototype '-sdg-2' attached)

Greetings

 

It seems that we still have to prove, with 
prototype(s),

a suitable design for the next version (2.0) of 
UBL

so I have been trying to prototype a set of 
possible

2.0 schemas and prove what design is 
necessary

in these to still allow polymorphism in 2.1 and 
even

in a theoretical 2.2 minor version.

 

The first step, already demonstrated, was to show 
that

there are problems introduced with the local 
declarations

of IDs and Codes in 1.0, hence the decision to 
remove

this design aspect by moving to a 2.0 major 
version.

The main problem introduced with these local 
elements

was in the fact that the instances for 1.0 would, 
if a

minor version used polymorphism with imports of 
these

schemas, require a change to the local elements 
from

default namespace without prefixes (e.g. 
in:Invoice/ID)

to element names with prefixes (e.g. 
in:Invoice/in:ID) for

tehm to be valid against the new schemas. This is 

considered to be an undesirable compromise of 
backwards

compatibility in one sense of our understanding of 
it.

 

I've tried to test this a bit further by making the 
change

to the IDs and Codes and then using the 
substitutionGroup

mechanism in subsequent prototypic minor 
versions

and I've found that this change may not quite be 
enough.

To allow minor version schemas to correctly 
validate the

major version instances with only minimal changes 
(e.g. just

schema location and the like) to the instances it 
appears

(as the attached prototype demonstrates) that we 
have to

make two further changes to the document 
schemas:

Firstly there are in UBL 1.0 some BBIEs declared in 
the 

document schemas rather than in the common (CBC) 

schema and these would have to be moved to 
CBC;

Secondly there are in UBL 1.0 some ABIEs declared 
in

the document schema and these too would have to 
be

moved to the common schema (CAC).

 

[ the attached file is a zipped file renamed 
.zzz from .zip ]

 

For those not too familiar with the UBL 
schemas, here 

is an example:

 

In the UBL 1.0 Invoice we have:

 

<xsd:complexType 
name="InvoiceType">
    
<xsd:sequence>
      ...

      <xsd:element 
ref="LineItemCountNumeric" 

          minOccurs="0" 
maxOccurs="1"/>
      ...

      <xsd:element 
ref="AdditionalDocumentReference" 

         
minOccurs="0" maxOccurs="unbounded"/>
      
....

    </xsd:sequence>
  
</xsd:complexType>

...

<xsd:element name="AdditionalDocumentReference" 

          
type="cac:DocumentReferenceType"/>
...

<xsd:complexType 
name="LineItemCountNumericType">
    
<xsd:simpleContent>
      <xsd:extension 
base="udt:NumericType"/>
    
</xsd:simpleContent>
  </xsd:complexType>

...

 

and this would, I believe, in 2.0, have to 
become something like:

 

<xsd:complexType 
name="InvoiceType">
    
<xsd:sequence>
      ...

      <xsd:element 
ref="cbc2-0:LineItemCountNumeric" 

           
minOccurs="0" maxOccurs="1"/>
      
...

      <xsd:element 
ref="cac2-0:AdditionalDocumentReference" 

          minOccurs="0" 
maxOccurs="unbounded"/>
      ....

    </xsd:sequence>
  
</xsd:complexType>

 

with both the document-specific BBIEs such as 
LineItemCountNumeric 

moved to the CBC schema module and the

document-specific ABIEs such as 
AdditionalDocumentReference 

moved to the CAC schema module.

 

As the examples in the prototype ('instances' 
directory) 

attempt to demonstrate, this allows instances to 
be

valid against all major and following minor 
versions 

when using the substitutionGroup

polymorphism mechanism for the minor version 
schemas.

 

In producing this prototype I came across a number 

of issues relating to the changes needed for 
2.0

 

1. Moving two Codes, ReasonCode and 
IdentificationCode 

to the common module (CBC) there may 
need

to be a renaming of the elements since the names 
are 

far less specific in 1.0 than the datatypes 
which

are tied to quite specific codelists (namely 

AllowanceChargeReasonCode and 
CountryIdentificationCode).

There is also a general principle here to which 
we'd 

need to adhere more in modeling with this new 
design:

that the more specific the datatype (e.g. a more 

specific codelist), the less generic should be 
the element

name.

 

2. We need to clarify whether an ID element 
should 

have a complexType named IDType or 
IdentifierType

There may be other improvements to such naming 

rules we'd like to make too (some type names 
seem

too arbitrary generally).

 

3. Does an xxxxCode element have to have a 

complexType name xxxxCodeType or is just CodeType 
sufficient?

Is this covered by NDR?

 

4. I take it that each code for which we have a 
codelist 

schema does still have to have a separate 
complexType

(such as AllowanceChargeReasonCodeType) declared 

for it in the CBC schema which then extends its 

codelist schema datatype. Is this so? Is there a 
rule that 

covers it (the rules may not have considered 
Codes

with codelists before in the context of the CBC 
schema 

since the codes were all locally 
declared).

 

5. The NDR and other 
schema module diagrams will need 

reworking since the patterns of imports will 
change.

I hope the attached prototype will help with 
this.

 

6. The 1.0 schemas have many fixed attributes in 
the 

datatypes (UBLAmount and the schema-defined 
codelists) 

and these could break the requirements for 
backwards 

compatibility of minor versions where they might 
need

to be changed (e.g. the UBL urls).

 

7. If the reasoning about the need 
to define all of the 

document BIEs in CAC and CBC schema modules are 
accepted

this may need to be explicit in the 
NDR

 

8. If polymorphism with the limited 
substitutionGroup 

mechanism is accepted there would need to be a 
consideration

of how to provide for both restriction and 
extension of the 

same types (e.g. to introduce an intermediate type 
suitably

named) - see previous prototype (sdg-1) but this is 
omitted 

from the attached prototype

 

9. There will likely be frequent occasions 
when a type to 

be extended was not explicitly declared in the 
previous version

(if only the types we changed in that version 
were explicitly 

included, as required for modular rather than 
blanket revisions).

This does then require (as in the 2.2 schema of the 
attached 

prototype - Delivery example) the import of earlier 
version

schemas such as the previous major version and with 
it the 

older namespaces and suitable prefixes. 
This then means that

we are likely to need rules to define separate 
suitably named 

prefixes for each version and these should ideally 
include

some indication of the version number (perhaps even 
for the 

major version). For example, I have used cac2-0, 
cac2-1, etc.

 

10. I do not forsee problems incorporating the ATG2 
CCTS 

schemas into the prototype (though I haven't done 
so here)

- see previous mail with such a design prototyped. 
But the 

complexities of the polymorphic versioning may be 
quite a

challenge, it seems, to keep it in step with the 
ATG2 design - 

mainly considering possible 
namespace aspects (as seen

in point 9 above). This concerns whether 
instances with the 

necessary multiple namespaces/prefixes for the UBL 
design

instances could be catered for in an 
ATG2-type set of schemas. 

Whether instances valid to the ATG2 schemas could 
have

the necessary complexity of namespaces to validate 
against 

corresponding UBL schemas is what seems 
an increasingly

challenging prospect 
as the real details are considered.

 

All the best

 

Stephen Green

 

 

 

xsd-derivation-prototype-ver-sdg-2.zzz