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

Title: Versioning, Namespace URI Design Discussion

 

I have now submitted an updated version of this note 
to the Steering Committee - http://lists.oasis-open.org/archives/opencsa-ms/200710/msg00005.html

 

If you have any comments, please let 
me know.

 

Thanks,

Sanjay

  

  
  From: Patil, Sanjay 
  [mailto:] 
Sent: Sunday, Sep 30, 2007 23:18 
  PM
To: ; Mike Edwards; 
  ; Ashok Malhotra; David Booz; Michael Rowley; Blohm, 
  Henning; Anish Karmarkar; Bryan Aupperle
Cc: Robin 
  Cover
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