Some comments on the Guidelines for Schema Customizations

[Ray Seddigh <RaySeddigh100@yahoo.com>]

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