Some comments on the Guidelines for Schema Customizations

Hi all,

I
had the opportunity to read this well-written Guidelines document
(The
UBL context methodology paper - Guidelines for the Customizations
of UBL v1.0 Schemas -Working Draft 1.0-beta3, 4/29/04).

I
enjoyed the thorough coverage of the document, and its elegant
balance of explication and concision.

In
response to requests for comments, below are some preliminary
observations.

Attached is an Open Office file version of these comments. For
completeness of reference, also attached is that
particular version of the original Guidelines document on which my
comments are based.

Hope
this helps.

Best,

Ray
Seddigh

__________________________________________________

Some
Comments on the UBL Schema Customization Guidelines Document

Ray Seddigh

In
these comments

The
focus is mostly on what a reader might expect from the document, a
few additional aspects of customization, further clarity of
exposition particularly for the many upcoming newcomers to UBL. A
few stylistic and copy-editing points are included
peripherally, at the end. 

Not
in these comments

Expanded
ideas about the relationships of tools, applications, and context
methodology are not included here, but reserved for a focused
discussion/document on such relationships.

General 

Mechanisms
for sharing, exchanging, and collaborative evolution of customized
libraries.

As
customized libraries are created using the guidelines of the paper,
quite often they will inevitably need to be shared, combined, or
collaboratively augmented. This need can arise within organizational
boundaries, across them, or both. The paper is silent or implicit on
the mechanisms for addressing this eventuality. More direct
explanation would be useful here. If there are existing methods, or
implied models, then those approaches could be referred to.

There
are pragmatic considerations as well. For example, are there any
coordination, storage, or registry requirements in order to make
elements of disparate customized libraries work together? If there
are none or if this topic will be addressed in the future, it helps
to state the same. Are namespaces the only
apparatus needed?

If
there are coordination, storage, or registry requirements, are they
centralized or distributed? Most importantly, what should the
customizer understand, or do, as they customize, in order to account
for these mechanisms (or plan for them if they are to be developed in
the future)?

Audience-

In
the preambulations of the document, it
would help to mention to whom this document is of use and addressed.
e.g.

Types
of individuals (Application developer, manager, standards developer,
customizer ...)

Communities
of interest / types of organizations: Industry groups, standards
groups, software vendors, government organizations, ...

CCTS
treatment - lines 61- 63 (Introduction)

While
reference is made to the CCTS via a link, a brief one paragraph
outline of CCTS would make the document more self-contained and
easier to follow. A simple diagram depicting the architectural
relationship of UBL and CCTS would add even more clarity.

Line
72 – Interoperability

Due
to the numerous connotations of "interoperability", it
would help to disambiguate by indicating which notion of
interoperability is intended here and elsewhere (interoperability
among what and what?). 

Interoperability
among UBL systems and EDI systems?

Among
trading partners using customized and non-customized UBL documents?

...

Lines
90-93

Could
be rewritten for clarity.

Lines
108-111 - Escape mechanisms

While
escape mechanisms can be inferred, they could be specifically
described or listed. 

A brief example would reduce the chance of
misinference.

Lines
118-120

“This
document does not provide instructions or how to incorporate UBL
schemas into other XML-based standards at
the semantic level.” Would this, or an equivalent paraphrase be
useful? Note this is somewhat distinct, although overlapping with
“customization for other industries”
point.

Line
164

Interoperability
among ...?

Line
306 - Context drivers

A
one line description of the “Business Process” context driver
would be useful here. 

The
same applies to context drivers that follow, but the first (Business
Process) is a central one, making it more useful to have a brief
description.

Lines
339-348

The
method for describing custom context drivers is illustrated here.
However, the method for naming such a custom context driver is not.
Does each customized context driver have a unique id (aside form a
long prose description) so that it can be distinguished from other
customized context drivers? Can context drivers be assigned
pointers/handles/variables such that they can be referenced inside
code or data without the need to mention a long prose description?

Perhaps
this is within the purview of NDR documents. Nonetheless the reader
can only be helped by the brief clarification of these points without
having to refer to other docs. 

Line
354 – Codelists

A
brief definition and / or example of codelists
and their overall role in UBL would provide for a useful transition
to this line, and show the relevance.

Line
353 vs. line 364

listID
and listURI – perhaps these can be further disambiguated to avoid
likely confusion of the two. May be an example can accomplish this.

Line
370 – Context chains.

The
two concepts of context hierarchy and “given hierarchical level in
that context” are referred to here, and implicit in what follows,
but they are not defined. Their relationship to “context chains”
could be clearer. Are they the same? If so one could use the same
name. If not, could one expand on the distinction? A brief definition
or a recap (not a reference to another document) would provide for a
smoother read.

Line
389

Doesn't
the “no constraint” about namespace name apply to restrictions as
well as to extensions? (BTW typo on line 389: not constraint => no
constraint).

Lines
488 – 500

Generally,
this section is likely to appear inscrutable to those new to UBL.
There are quite a number of references to new, undefined (in this
paper) topics, acronyms, and names of constructs. Appears as an
enumeration of concepts versus an expository rendition of how these
concepts relate to each other, to context methodology, to the UBL
type library, and the needs of the customizer. Are all these
references central to the goals of this paper? If so, perhaps a
rewrite of these lines along with an example would make for a clearer
read. As an aside, stylistically, it may help to make some of the
sentences in this section shorter.

Also,
for better legibility, one could place the related NDR picture
in-line here, vs. making a reference to it. 

Line
507 schema modules

A
one line description of a schema module here would help differentiate
it from other neighboring concepts mentioned in this paper.

Line
508 extension, refinement

“before
extending or refining” --- The distinctions between refinement,
extension, restriction and narrowing would be useful to mention
somewhere early in the document.

Line
513

Anaphora
resolution – which namespace does “that namespace” refer to?

Minor
Typos and Copy editing

Lines
283-299

These
lines seem to be a verbatim repeat of lines 227-241. If emphasis is
the goal, perhaps a paraphrase or summary would avoid the duplication
of the paragraphs.

Line
67 "lessons"

Line
78 "mechanism that took a standard"

Line
92 "all possible values of it" ?

Ray-Seddigh-comments-on-UBL-context-methodology-paper.sxw

wd-cmsc-cmguidelines-1.0-beta3.pdf