RE: [ubl-cmsc] review of Customizations Document

["Matthew Gertner" <matthew.gertner@acepoint.cz>]

Wow, I agree with Eduardo. This is great feedback, and I wish we could
get more of this type and level of detail from a variety of industry
groups (hint, hint). Thanks, Dan! I have taken some liberties in slicing
and dicing your original mail, with my own comments inline:

> The introduction and background information look pretty good. It was
after
> this that I started
> having difficulties with the structure. In my copy the numbering of
the
> levels is not correct
> which doesn't help, so some of this may be just that problem. Anyway,
I'm
> think about an
> organization and titles that would look something like this:
> 
> 		1 Introduction
> 
> 		2 Background
> 			2.1 The UBL Schema
> 			2.2 Customizations of UBL Schemas
> 			2.3 Customization of Customizations
> 
> 		3  Compatible UBL Customization
> 			3.1 Use of XSD Derivation
> 				3.1.1 Extensions
> 				3.1.2 Restrictions
> 				3.1.3 Combined Extension and Restriction
> 			3.2 Documenting the Customization
> 			3.3 Identifying Extensions - use of xsi:type
> 			3.4 Component design - complextype for
everything
> 			3.5 Use of Namespaces
> 
> 		4 Non-Compatibly UBL Customization
> 			4.1 Use of Ur-Types
> 			4.2 Building New Types
> 
> 		5. Future direction
> 
> 		Notices

Definitely some good organization ideas here.

> Section Compatibility: Customization through Derivation
> -------------------------------------------------------
> 
> There is a lot of references things that can/can't be done without a
> concrete example. It is
> sort of like a textbook where the author will do something like that
and
> say "derivation or
> proof is left to the reader", I think if we want to allude to things
that
> we should give a
> supporting example or remove these references. An example is "(not all
of
> which can be
> accomplished through direct XSD derivation)".

My feeling after the first draft of the document was that the biggest
lack is concrete examples. The problem is that I am an XML geek and not
a business expert (and this applies to many of the most active members
of this SC), so we made need external input to beef up the examples. The
ideal (as you imply at one point in your comments) would be to have a
single, consistent example that is used to provide concrete illustration
of the various points.

> The three bullet items are a little confusing. First I would add
another
> level of bullets that
> would help the example above. I would create the following
> 
> 	o Compatible UBL Customization
> 		- Content of bullet 1
> 
> 	o Non-Compatible UBL Customization
> 		- Content of bullet 2
> 		- Content of bullet 3

Sure.

> Bullet 2 I was generally confused about the content. I understand
where it
> is trying to go,
> but was lost in these words. I think this should be a section of its
own
> with an example.

Yes, I stand by the wording of this, which I believe to be correct, but
it screams out for an example.

> Bullet 3 Again I think this is a section we should have that "reviews"
the
> general naming and
> design decisions. Also there is a "recommended" status on this, I
would
> think this should be
> "required" if this is to be a public schema available for others to
extend
> (per the context
> model and requirements).

I can see the merits of requiring this for consistency's sake. I think
we need to get more input from potential customizers about whether this
is going to cramp their style. The right way to get this input might be
to require a parallel element/type hierarchy in extensions and see if
anyone screams.

> Section Compatibility: Context and Documentation
> -------------------------------------------------
> 
> The second and third paragraph in this section seem out of place. If
you
> think these are
> needed, I would put them in a Future Directions section of their own.
> right
> now they confuse
> the issue of documentation.

Not sure if I agree with this, since the referenced paragraphs help to
explain the need for good, clear, consistent documentation.

> It seems to me (and based upon the illustration) that each context
change
> should be one set of
> schemas/extensions. I apply each one individually. As such I should be
> able
> to just place the
> documentation at the "top level" of the schema and not each component
as
> required in the
> paragraph following the bullet list. If you allow multiples, then the
need
> for documentation
> at each component becomes necessary and not all contexts may be
applied to
> every change.

Once again, I'm not sure I agree with this. If, say, a U.S. insurer is
creating a customized P.O., wouldn't they have extensions relating to
the U.S., to insurance and to both, all in the same schema?

> I think we need a definitive statement the multiples are allowed or
not.
> The example actually
> shows multiples so this would need to change accordingly. Personally I
> don't think you want to
> allow multiples, otherwise how to manage the extensions? With
multiples,
> your diagram is not
> as clean and it might be impossible to implement this stuff.

So how do you create new types that are the result of two different
context drivers?

> The second paragraph alludes to ways that are non-compatible that will
> potentially fix
> reordering/placement issues (not defaulting to the end of the
structure).
> If this is true we
> need an example of this - if I'm reading it right, I don't think this
is
> possible.

Does Eduardo know something we don't? :-)

> I'm curious why making a new type, of existing UBL elements would be
> consider to be non-
> compatible. Assuming I'm not changing the defined use of those
elements,
> just that I need a
> different group shouldn't be a reason to come up with the
non-compatible
> label. Also I guess
> this implies that I can only add to existing complexTypes and be
> compatible, I can't create a
> new type. I need to check the schema, is there a complex type for the
high
> level document
> object? is for the PurchaseOrder is there a PurchaseOrderType that I
can
> extend?

Perhaps we need a better definition of compatibility, or rather a clear
definition of levels of compatibility. Clearly if I use only UBL CCs
then at some level I have create a UBL-compatible type even if it bears
no relation to any aggregate type in the actual library. The point we
are trying to make clear here is that a customized Order type, for
example, created from the Ur rather than UBL type, is *not* compatible
with the UBL Order in terms of reuse (i.e. you can't stick it somewhere
where a UBL Order is expected). I would recommend that we formally
define 2 or more levels of compatibility and update this section to
reflect more accurately what we mean by compatibility.

> Can I have a mixed compatible and non-compatible set of extensions in
the
> same schema? or if I
> need non-compatible methods, should the whole set of extensions be
based
> upon the Ur-types
> instead of the UBL types? Will need reasons for this.

This question is perhaps more complex than it might seem, since the use
of Ur Types influences the enclosing structure as well (e.g. I can't put
an Ur-Type-derived Address element inside a UBL Order document). This
needs to be well-illustrated with examples as we have already
established. As far as mixing compatible and non-compatible
customizations, I don't see an issue with this as long as the types
don't enclose each other.

> I found the last paragraph of this section unintelligible - I don't
know
> what you are trying to
> tell me here.

If you are talking about section 4.1, I don't really understand it
either. Can some clarify? I almost get it but an example would be very
helpful.

> I would move the last paragraph of this section to a "General Naming
and
> Design Requirements"
> section.

I guess the NDR issues should be (and are) discussed in another document
entirely.

> We need at least one complete example. For instance I don't see why I
> can't
> use an adapter
> schema methodology with redefine to make this work unless you show me
what
> you intend. The
> little examples are ok for what you are covering, but no where do I
get
> the
> big picture. This
> would then show the namespace issues, how to document, etc. May need a
> non-compatible example
> as well.

Can you give a concrete example of the adapter approach?

> How do I determine if a given Context customization exists already?

Very good question. I am guessing that the short answer (for this
release at least) is "you don't". Perhaps in some future release we will
tie into a registry of some sort. Anyone disagree?

> Are there any rules for substituting a more generalized and useful set
of
> customizations over
> an existing one that may not be as good or complete?

Not now (again AFAIK). Can you give an example of this?

> Is there a defined order of the Contexts? If there isn't it would seem
to
> make finding common
> schemas more difficult. Suppose A defines a Business, Industry, then
> Geopolitically
> arrangement, but B comes at from a Geopolitical, Business, Industry
view.
> Both A and B use the
> same values, it might be difficult to find this without some order
> involved.

No order is defined. Not to be a broken record, but can you (or someone)
give an example of where the resulting type would be different depending
on the order of application of context drivers? I remember that the last
time we drafted a real context rule language there was some provision
for ad hoc priorities attached to specific rules. Would this be
sufficient? (I believe this is discussed in the good ol' ebXML context
methodology document.)

> Related to above. I'm in Insurance and only in the US. Now if someone
has
> created a set of US
> extensions to the Purchase Order, we are saying I have to accept those
and
> add mine? Or is
> there a way to come up with just US Insurance specific changes? I
think
> the
> plan is that I
> would have to take the US extensions, restrict things out I don't
want,
> then add my US
> specific things - correct?

My understanding is that, for now, every organization comes up with its
own extensions. There aren't any provisions for exchanging extensions
AFAIK.

> Can I restrict allowed derivations with XSD schema features? Would UBL
> ever
> use these?

What kind of features do you have in mind. The supported features of XSD
have been established by the NDR SC, so I imagine some very solid
justification would be needed to change this.

> All of this seems to assume that UBL is the starting point, will we
allow
> someone to import
> another organizations elements and methodology? My guess is that this
> would
> cause a non-
> compatible UBL customization. I think we should probably make this
clear
> and maybe have a
> strong reason why.

If UBL isn't flexible enough to let an organization meet their
information-exchange requirements while remaining UBL compliant (at
least in the large majority of cases) then IMO we are doing something
wrong.

> I need to review the schemas, but we say our elements are based upon
> restricting/extending the
> Ur-types so they will be somewhat compatible with the non-compatible
> methods. I don't think
> this is the current state of the schemas and should be by the time we
> publish this.

Didn't understand this. What schemas are you referring to?

> One issue I think we need to answer is the portability/maintainability
of
> our extensions. It
> looks like you intend to modify the UBL schemas directly (unless an
> adapter
> method is used).
> How can I manage my extensions in a manner that makes them easy to
port to
> the next release of
> UBL or apply it to someone elses extensions?

Yes, this needs to be addressed. Ideally changes to UBL would be such
that most if not all extensions would remain valid, but I think someone
will have to play around with some examples to establish to what extent
this is the case a) in theory and b) with regard to the current UBL
library.

> Should we have a flag/documentation that labels an extended schema as
a
> compatible or non-
> compatible. You could write some things to check what we extended, but
it
> would be clearer to
> have this stated rather than calculated. Also can I have a mixed
schema,
> part based upon UBL
> and just a few things that come from the non-compatible side. I can
see
> two
> cases that might
> have different answers:
> 	- Needing a type based upon existing UBL elements
> 	- Needing the UR-type to change required elements

I like the idea of compatibility levels or compliance levels, and we
could have tags (or probably attributes) defined that could be included
at the schema or type level (in the case of a "mixed" schema) to
document this appropriately.

> I think we need a section to cover questions like:
> 	- How to apply namespaces
> 	- element naming conventions for extensions
> 	- component design requirements for extensions (an element based
> upon a
> type, no local
> 	elements, etc)
> 	- where elements/codes get added in the extension process

Once again I think this is the job of the NDR SC and it's close to
completion.

> Is there going to be a mechanism to promote extensions back into the
UBL
> core schemas? What is
> the impact on my extensions?

Probably right now to be submitted to the LC SC for consideration.
Opinions?

> What are the versioning requirements for UBL in terms of adding a
required
> element? Is
> this a major or minor version? This impacts how my extensions work. If
I
> know that unless
> we go to a major release (breaking backwards compatibility), I know
that I
> won't get a
> required element in an existing structure. Now it might be that it
should
> be required, but
> until a major release, it should remain as optional.

Yes, it would require a major release since it breaks backward
compatibility.

> I think we may have a problem like above with extensions of
extensions.
> Might need some
> recommendations or warnings that adding a required element higher up,
may
> break
> compatibility lower down as the element order shifts based upon
additions,
> and required
> elements might break an existing stream.

Well if the extension is part of an "extension library" this shouldn't
be a problem since it doesn't change the underlying UBL schemas.

Cheers,
Matt