• From: "G. Ken Holman" <gkholman@C...>
• To: "xml-dev@l..." <xml-dev@l...>
• Date: Fri, 08 Apr 2011 18:54:22 -0400

In UBL the committee defines a common library of everything and 
issues document-level schemas that incorporate constructs, most of 
which are optional.  Every schema starts with an optional extension 
point (supporting at some point therein xsd:any) first child where 
information not defined by the committee is added.

We expect user communities to define a "UBL Customization" which 
combines a *subset* of the committee-defined constructs with an 
extension under that first child of constructs not available from the 
committee's common library.

I have an OpenOffice add-on for UBL 2.0 enabling the user community 
to specify in a spreadsheet which optional constructs to keep in a 
customization and which from the fully-defined set to remove.  This 
tool reads in the committee-distributed schema files and comments out 
the user's undesired constructs by using an XML comment around the 
declaration (thus preserving the committee information in the schema 
for doubting Thomases who don't believe the user's schema's heritage 
is the committee-distributed file).

That leaves the user community with a schema of their 
subset+extension that they happily use between members within the community.

The UBL Customization guidelines 
http://docs.oasis-open.org/ubl/guidelines/UBL2-Customization1.0cs01.pdf 
talk about this in more detail.  Chapter 4 is the section on validation.

Figure 23 is a suitable validation processing model for instances 
from like-defined subsets.

What if an outsider sends in, say, an invoice from a community that 
has chosen a different subset of available constructs in their UBL 
customization?

Figure 24 is a suitable validation processing model for instances 
from possibly differing subsets.  It might be that the instance will 
validate, in which case the application can work with the data.  But 
it might be that the instance is using a construct not allowed in the 
schema.  This is a barrier to an application running an unmarshalling 
front-end like JAXB.  Not only would validation reject the instance, 
but there would be no place in the data structures to place the 
foreign construct.

One approach to guarantee the application can read the instance, even 
if it arrives with foreign constructs, is to prune the instance of 
the foreign constructs, noting in the application that you have, 
indeed, done so (though not, necessarily, what).  The application now 
runs (because the instance validates), but it runs with the knowledge 
that *something* had to be removed from the instance to work.  With 
this knowledge it can choose an appropriate disposition.  But it 
wouldn't have been able to do so had the instance not been pruned, 
because the API front-end would have rejected the instance.

So a community can have its cake and eat it too:  instances that 
happen to validate (be they from the community or from outside the 
community) are handled quickly, and instances with foreign constructs 
just go through an extra couple of steps.

I think subsetting the schema is important because it could be a 
burden on applications to support the entire schema when only a part 
of it actually has a chance of being used.  Penalize only those 
instances that contain foreign constructs, don't penalize all instances.

That's one aspect of compatibility: the presence of foreign 
constructs.  For backward compatibility, the other important aspect 
of compatibility, UBL 2.1 only introduces optional constructs as 
children of existing UBL 2.0 constructs.  Mandatory constructs are 
certainly allowed as descendants of the introduced optional constructs.

Using the process in figure 25 cited above, a heterogeneous network 
of nodes supporting UBL 2.0 and UBL 2.1 can interoperate without 
barriers.  UBL 2.1 systems can read UBL 2.0 instances as if they were 
UBL 2.1 instances (which, in fact, they are guaranteed to be).  UBL 
2.0 instances can read UBL 2.1 instances after pruning those that 
don't restrict themselves to UBL 2.0 constructs.  In this way, the 
entire network of nodes does not need to migrate to UBL 2.1 at the 
same time.  And this is true for any UBL 2.x ... the one pruning 
filter for UBL 2.0 will work regardless of the foreign constructs in 
UBL 2.x.  UBL 2.1 systems would have their own UBL 2.1 filter to 
accommodate instances from subsequent UBL minor revisions.

In this way, the investment by stakeholders in UBL 2.x is protected 
from changes in UBL 2.y (where x < y) and need not change until they 
choose to support the later minor revision, yet still 
interoperate.  No doubt our user community will continue to come to 
OASIS looking for new minor revisions of UBL.  UBL 2.0 supports 31 
document types.  UBL 2.1 in its current state supports 65 document 
types, and should be finalized before the end of the year.  Yet the 
common library grew by, I think, less than 10%.  Who knows how many 
document types will be in UBL 2.y?  But a UBL 2.0 instance will still 
be allowed, and a user's investment in their UBL 2.0 software will 
still be paying off.  It is robust, not brittle.  They need only 
upgrade their software if they need access to the introduced constructs.

I hope this helps.

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

At 2011-04-08 23:17 +0100, Fraser Goffin wrote:
>We use an XML schema library that models the majority of the entities
>that we need to express business transactions. These typically can be
>quite large complex types that contain the superset of all properties
>for an entity. For example we might have a Customer complexType that
>has 20 or 30 elements. When we use these complex types within the
>context of creating a business transaction, there is an inevitable
>discussion about whether a type should be specialised for that
>particular context by applying greater constraints. For example, it
>might be that for a particular business service schema, only 10 of the
>elements in the Customer type are actually required, at least for now.
>So we could create a new Customer type within the service schema that
>only contains those 10. Others would prefer that the whole type is
>used and all of the elements in it's content model remain as optional.
>Part of the rationale for this is to minimise the possibility of
>having to deal with a breaking change to the schema some time in the
>future as/when requirements change and some of the excluded elements
>could be required. A case is also made for leaving the full type so as
>to provide a greater chance that the service schema will be more
>reusable, and that by applying greater constraints (not limited to
>just removing parts of the type but also tightening cardinality or
>applying facts and so on) makes the service contract 'brittle'.
>
>On the flip side, others prefer to have a service contract [schema]
>which applies the fullest set of constraints and give the user of that
>schema the best possible specification in terms of what data is
>expected and would be valid in the context of the business
>transaction. This is more in line with the concepts of 'consumer
>driven contracts' which often have the (desirable) characteristic of
>being much more communicative than schema that have few constraints
>(ie. are packed with mostly (or completely) optional elements of type
>xs:string of unspecified size or form).
>
>This subject often gives rise to some heated debate that somewhat
>predictably  tends to centre around subjects such as versioning,
>compatible/incompatible change, integrity of the base data model, ease
>of use for service consumer, potential service reuse and so on...
>
>So I thought I'd invite members of this community to comment on
>whether you favour very open lightly constrained schema when defining
>business services (at least when expressing the data content as XSD)
>or whether you prefer to try and specify all constraints even at the
>risk of generating greater churn (aka: incompatible change).
>
>Fraser.


--
Contact us for world-wide XML consulting & instructor-led training
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/x/
G. Ken Holman                 mailto:gkholman@C...
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal

• References:
  • Service Constraints
    • From: Fraser Goffin <goffinf@g...>