Re: [sca-bindings] Versioning, Namespace URI Design Discussion

[Simon Nash <NASH@uk.ibm.com>]

Sanjay,
Thanks for this very helpful sumary of the namespace issues and 
suggestions for how to address them.

Regarding the choice of Java package names, I believe this should be a 
matter for the sca-j TC to decide, as all the specifications that use Java 
package names fall under this TC.  I would therefore suggest that we move 
discussion of this topic to the sca-j list.

    Simon

Simon C. Nash, IBM Distinguished Engineer
Member of the IBM Academy of Technology
Tel. +44-1962-815156  Fax +44-1962-818999



"Patil, Sanjay" <sanjay.patil@sap.com> 
01/10/2007 07:18

To
<sca-bindings@lists.oasis-open.org>, Mike Edwards/UK/IBM@IBMGB, 
<martin.chapman@oracle.com>, "Ashok Malhotra" <ashok.malhotra@oracle.com>, 
"David Booz" <booz@us.ibm.com>, "Michael Rowley" <mrowley@bea.com>, 
"Blohm, Henning" <henning.blohm@sap.com>, "Anish Karmarkar" 
<Anish.Karmarkar@oracle.com>, "Bryan Aupperle" <aupperle@us.ibm.com>
cc
"Robin Cover" <robin@oasis-open.org>
Subject
[sca-bindings] Versioning, Namespace URI Design Discussion







This email is to fulfill an AI assigned to me during  the last conf-call 
of the SCA-Bindings TC. As I understand, the AI was to identify the 
various top level issues concerning versioning of artifacts, namespace URI 
design, etc.  Since this topic is also of interest to the other Open CSA 
TCs, I have included the chairs of those TCs on the recipient list of this 
note.
Following is what I think are the high level questions (along with my 
commentary) concerning versioning, namespace URI design, etc, for the Open 
CSA TCs.
- What version number should be used to describe the artifacts 
(specifications, schemas, WSDL files, etc.) produced by the different Open 
CSA TCs? 
  I believe the Open CSA Steering Committee recently resolved to make a 
technical recommendation for all the Open CSA TCs to adopt the same 
version number. As I understand, the plan is to use  '1.1' as the version 
number as of now.
  As per the OASIS guideline for Metadata and Versioning [1], the version 
number represents a significant body of work carried by a TC often leading 
to an OASIS standard, and therefore the version number typically would not 
undergo changes during the TC's life time. The version number of artifacts 
should not to be confused with the various stages of the artifact drafts 
produced by the TC (e.g. working draft 01, working draft 02, committee 
draft 01, committee draft 02, etc.), and the revisions of each stage of a 
draft  (e.g. committee draft 02 rev 1, committee draft 02 rev 2, etc.). 
Please see the OASIS guideline for more details.
- Should the version number be part of any namespace URI formulated by the 
Open CSA TCs? 
  I think we should consider the design and change of namespace URI as a 
separate issue from the versioning of the artifacts providing definitions 
for that namespace URI. Namespace URI is typically changed only when some 
definitions under the namespace undergo backward incompatible changes. 
There are situations where the version number of artifacts may change but 
the namespace URI may remain the same. For example, a TC may decide to 
bump the version number of specifications (e.g. use 1.5 instead of 1.1) 
merely to reflect the amount of new work that made into the new version, 
however the new version as such is still backward compatible with the 
previous version.
  A solution here is to not use the version number in design of the 
namespace URI, but use some other metadata (such as year and month of when 
the backward incompatible change to the definitions under the namespace 
URI is introduced) . For example, the http scheme namespace URI defined by 
the version SCA Assembly TC specifications could be  - 
http://docs.oasis-open.org/[tcShortName]/[tcProductName]/[yyyymm], where 
yyyymm stands for the year and month in which the TC voted on the first 
committee draft of the artifacts.
- How to formulate a namespace URI, which is used and defined by multiple 
Open CSA TCs? 
  The OASIS guideline for URI design [2] recommends that the http scheme 
namespace URIs defined by OASIS TCs to begin with: 
http://docs.oasis-open.org/[tcShortName]/, where the [tcShortName] is the 
short name of the TC such as sca-assembly, sca-bindings, sca-j, etc. So 
when multiple Open CSA TCs plan to contribute to the same namespace URI, 
we have a conflict. Looking at the contributed material to the different 
Open CSA TCs,  it seems that we currently have this problem, for example, 
the namespace "http://www.osoa.org/xmlns/sca/1.0"; is defined by the schema 
for SCA Assembly (contributed to SCA-Assembly TC), schema for SCA WS 
Binding, SCA JMS Binding (contributed to SCA-Bindings TC), etc. A solution 
here would be to use the short name of the member section (i.e.OpenCSA) 
instead of short name of he TCs, that is, the namespace URI shared by the 
different Open CSA TCs would begin with 
http://docs.oasis-open.org/opencsa/ However it would be advisable to 
consult the OASIS staff if we were to adopt such a solution since it is 
technically in violation of the OASIS guidelines.
- Should the namespace URI be dereferenceable? If yes, what document 
should be returned when a namespace URI is dereferenced?
  I think the namespace URI should be dereferenceable, and a RDDL 2.0 
document describing the namespace should reside at the namespace URI. The 
RDDL 2.0 document at the namespace URI can then include pointers to the 
various artifacts providing definitions for the namespace along with a 
brief introduction for each artifact, description of the namespace change 
policy, etc. We can look at some of the RDDL based namespace description 
documents created by  the WS-RX TC [3].
- Should the decisions adopted by a TC regarding versioning, namespace 
design also reflect in its language specific definitions, if any, such as 
java package names?
   May I suggest the right experts in this area (not me) to chime in here. 

I hope the above set of questions and commentary is helpful in 
understanding the high level issues and making the initial set of 
decisions regarding namespace design, versioning of artifacts, etc.  For 
the actual concrete resolutions, we should reference the detailed OASIS 
guidelines, etc.
Thanks, 
Sanjay 
[1]  
http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata03.html 

[2] 
http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingV07.html#URI-Design 

[3] http://docs.oasis-open.org/ws-rx/wsrm/200702 






Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU