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

["Stephen Green" <stephen_green@seventhproject.co.uk>]

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