Re: Versioning, Namespace URI Design Discussion

[Anish Karmarkar <Anish.Karmarkar@oracle.com>]

A very nice set of questions and commentary.
Few comments inlined below.

-Anish
--

Patil, Sanjay wrote:
> 
> 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.
> 

Regardless of whether there is a single NS for all the OpenCSA TC 
schemas or multiple NSs, I think having an OpenCSA prefix makes sense.
For example:
If it is a single NS then something like 
http://docs.oasis-open.org/OpenCSA/sca/YYYYMM
If it is multiple NSs then something like 
http://docs.oasis-open.org/OpenCSA/sca-binings/ws/YYYYMM

> - 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?
> 

+1 to dereferenceable URL and having RDDL document at the URL.

>   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_
>