[ubl-ndrsc] MINUTES: Face to Face 4 Feb 2003

[Lisa-Aeon <lseaburg@aeon-llc.com>]

The minutes below are from today's NDR Face to Face.  Please read and respond via email or tomorrow's NDR call, which is at the regular NDR time.  For further details, consult the NDR agenda for tomorrows call.

 

NDR Roll Call
Jon Bosak (pm)
Dave Carlson (observer)
Mavis Cournane
Mark Crawford
Fabrice Desre
Arofan Gregory
Eduardo Gutentag (pm)
Lisa Seaburg
Gunther Stuhec
Paul Thorpe (pm)
Jim Wilson (observer from CIDX)
Dan Vint (observer from ACCORD)

 

Discussion Topic 1: Documentation

 

In terms of documentation the following areas of discussion need to be explored:
1. Do we still agree that XHTML should be used for embedded documentation as is the plan of record.
2. Mark argues that we should not duplicate any documentation that will be held in the ebXML registry. Any additional documentation required should be held by the equivalent Part 0 of the schema specification.
3. Gunther proposes using a customized Docbook schema in addition to the registry and implementors would have option to use the registry or the schema depending on whether they are offline.
4. Gunther proposes putting the schema in the registry and holding all the embedded documentation in the schema.
5. Gunther proposes putting a link from the schema to external documentation and the schema resides in the ebXML registry. This external documentation could be held in a native XML DB.

 

Gunther argues that XHTML does not meet all requirements. Our agreed plan of record said we should use XHTML for all embedded documentation of BIE and CCT.  Gunther believes this is not very useful because it XHTML describes layout and we would not want to have any layout info in our schema. Gunther proposes the use of a customized Docbook which is much more semantically structured and has all the elements we would need to use.

 

The one question is it overkill? Gunther argues that we should take a subset of Docbook. It is very helpful for the auto generation of glossaries.
It is easy to generate some HTML files using XSLT from Docbook. We could ask the Docbook TC to provide us with a Docbook schema customized to meet UBL requirements.

 

We also discussed the possibility of using simple Docbook i.e. DocbookLite but felt this would not be sufficient without customization.
Both Eve Maler and Norm Walsh should be able to provide information available.

 

There are 2 different documentation annotations required. One is based on the Core Component characteristics and the second is additional documentation for elements and types. Gunther has a proposal on how to resolve these. For the second type of documentation Gunther suggests Docbook. For the Core Component characteristics Gunther is proposing his own schema.

 

Mark - if we use an externally derived schema, what is the impact of importing this into our schema. Arofan believes, there is no impact as long as we can get it in a few months. What is the impact of a DocbookLite schema adhering to a different set of NDR rules. They have different design rules anyway as they are looking at specific rules for documentation.

 

Question?
Should we customize full Docbook and restrict it.
Should we ask for a DocbookLite schema.
Should we restrict and customize DocbookLite.

 

Gunther will check the DocbookLite schema and see if it has all the elements we need.

 

What are our requirements for documentation. According to Arofan:
- We need something that allows documentation of specific constructs without having to take in higher level tags.
- Easy and simple to use.
- Should be familiar and enjoy popular support.
Consult Arofan's position paper on embedded documentation on the NDR Portal for more info. Additionally see Gunther's presentation posted to the list on Feb 3rd 2003.

 

Mark wants to know why we don't just use the proposed ebXML registry. Why do we need additional documentation in the schema. Does the  documentation that Gunther and Arofan wish to provide go above and beyond what is called for in Section 7 of the CCTS?

 

Gunther presented his slides on Documentation that should answer Mark's question.
It is normal practice to make documentation available in the schema rather than accessing an online registry. Mark does not buy in to the regurgitation. How do we maintain consistency of embedded documentation with CCTS registry. If we are going to do Stored Business Contexts as part of our embedded documentation we need to be compliant with rule S35 and S36 with CCTS. What UBL produces is a set of BIEs in the schema library and we insert a lot of metadata, which we  donate to the registry - there is no place for the BIEs and registry to get out of synch because we are passing this directly to the registry.

 

Mark disagrees with Gunther's proposal to put into the documentation, an example of an XML instance of what a particular Context Type is describing.

Gunther argues that the implementation specific information about how you receive this in an XML instance is not provided in the registry.

Furthermore you need links and references to external things like UML class diagrams and some people might want to deal with the schemas offline.

 

Arofan makes 2 further points
We have inside annotation a UBL documentation namespace and for each piece of doc we have 2 things
1. an element that carries the values from the spreadsheet as attributes (as Gunther shows in his slides)
2. an element called something use and use has free form content and it simply provides freeform structures that allows us to put in narrative instructions about the use of this thing. The thing this solves is there are many different kinds of documentation for many different kinds of things. It would be simpler to use. You have the structured documentation for the spreadsheet stuff and the free form stuff for descriptive stuff.

Arofan argues that Gunther's use is too restrictive. Mark says the registry supports freeform text. Gunther says the auto generation of documentation of freeform text will not produce anything very useful. If freeform text is very granular this might be better.

 

Mark Crawford is opposed to replicating information that is already stored in the registry. He has deep reservations about the use of Docbook as he feels the descriptors do not fit what we need. What we need is Part 0 of the schema specification for every part of the schema.

Arofan says we should  not create a dependency between the creation of an ebXML registry and the implementation of UBL. UBL needs documentation. We don't know when that registry will exist. Mark says there is a fully conformant registry. Right now not a single place for developers to go.

 

Gunther argues if we don't have a registry, we should define a registry according to our rules and requirements in accordance and aligned to the CCTS.

 

Lisa argues UBL 1.0 has to be available for free with the documentation. The requirements in the UBL Charter state that this product is royalty free and publicly available to all.  There is no threshold for entry.  With this in mind, the dependency on any external registry has to be considered outside of the scope of the charter.

 

What about the requirement for an overall implementation guide to be drawn from the body of the schemas themselves, we have some up front stuff and the embedded documentation handles only detailed stuff.

 

Discussion Topic 2: Context Methodology
This is a discussion about Phase 1 Context Methodology i.e. Context customization by hand rather than automated.

Eduardo goes through the paper that Matt Gertner sent. It talks about why we need customization, how is derivation done? To understand this we need to understand the concept of the Ur schema and what is the difference between this and the UBL 80/20. This document summarizes where we are and what we are going to do. It summarizes the Guidelines we are going to give users for Phase 1 of customization.

 

The paper will be looked at under the following headings:
Is Matt's paper understandable?
Does it cover everything and does it touch on all the relevant points?
Can anything be safely deleted?

 

Bill Burcham put forward a set of requirements for context methodology customization.  Eduardo feels that most of the requirements are okay and some are contentious. Through XSD derivation from the Ur schema we can meet all of Bill's requirements which would not be equivalent to UBL compliance.

 

***We need to vote on our proposal arising out of Minneapolis from the F2F on the use of the 80/20 principle for context methodology handling.

One possible thing missing that arose out of our Minneapolis F2F discussion are:
infinite recursion. This might need to be considered by Matt and Bill and added to Matt's paper.
The simplified discussion of context drivers needs to be expanded. There is a draft document, that is out of date and needs to be in OASIS format.

 

Some summary needed on when to use XSD Derivation and when to use the UR schemas and what are the consequences.

With the ur type you can't use the UBL namespace.

 

What is the difference between hand modification straight from the first UBL schema and using the UR schema? You have no claim to UBL compliance. The 80/20 schema is a valid UBL restriction of the UR schema.

 

Jon suggests to make the intent clearer talk about making modifications to the UBL schema rather than the 80/20 schema.

Section 3 of the paper should be pulled forward. The concept of the ur schema should be a new section.

 

The ur schema will not necessarily physically exist but the 80/20 schema which is the UBL schema will exist.

 

It is understandable but only to a specific audience. We should call the document "Guidelines for customizations of UBL schema". It also needs to be structurally reorganized. For immediate release we need to put an executive summary giving a bird's eye view of Context Methodology in this paper. The target audience for this would be non-technical.

 

We need to put in some simple examples of how to do this.

 

Should we eliminate the detailed discussion of what XSD Derivation is. Anyone doing this should know what it is anyway. If we don't eliminate it we better ensure that how we describe it is 100% consistent with the XSD specification.

 

Jon suggests as a naive user it is very important to know what is disapproved. With this in mind it is critical that we emphasize that we do not envisage derivation from the UR schema as the method of choice. Rather this is a last resort and should only be done where XSD derivation does not meet the specific user requirement. It needs to be strongly emphasized that UR schema derivation is significantly less that XSD derivation in terms of compliance. In short Ur schema derivation is NOT UBL compliant, rather it is a lesser of many possible evils.

 

Mark also emphasized that NDR will need to hammer out what XSD features will not be used.  There is a XSD comparison matrix being used by the UNCEFACT ATG group that UBL is listed in, and gives a clear indication of which XSD features are being utilized by which groups. 

 

Our NDR document should be equally clear on which XSD features UBL schemas do and do not employ.

 

 

 

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.441 / Virus Database: 247 - Release Date: 1/9/2003

Attachment: Lisa Seaburg.vcf
Description: text/vcard