Versioning, Namespace URI Design Discussion

["Patil, Sanjay" <sanjay.patil@sap.com>]

Title: 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