Title: Versioning, Namespace URI Design Discussion
Hi Mary, Robin,
I am planning to forward my note below to the Open CSA
Steering Committee so that they can discuss it and possibly make a
recommendation to all the Open CSA TCs. Before I do that, I wanted to check with
you whether it would be ok with OASIS for multiple TCs to specify definitions
for a single namespace URI. I am sure this idea leads to questions such as -
which particular TC owns the namespace information document (e.g. RDDL 2.0
based) if the namespace is fleshed out by multiple TCs? I also think that we can
arrive at some workable solution. But before we go there, I wanted to make sure
that the OASIS staff is not going to rule out the possibility of sharing a
namespace across multiple TCs. It will be great if we can resolve this
issue via email before Friday (when the Steering Committee meets
again).
-- Sanjay
From: Mary McRae [mailto:]
On Behalf Of Mary McRae
Sent: Monday, Oct 01, 2007 5:25
AM
To: Patil, Sanjay; ; 'Mike
Edwards'; ; 'Ashok Malhotra'; 'David Booz'; 'Michael
Rowley'; Blohm, Henning; 'Anish Karmarkar'; 'Bryan Aupperle'
Cc:
'Robin Cover'
Subject: RE: [sca-bindings] Versioning, Namespace URI
Design Discussion
Hi
Sanjay,
I’ll chime
in and hopefully save some discussion. There is no way for more than one TC to
create any single artifact so I’m not sure what is meant by “- How to formulate
a namespace URI, which is used and defined by multiple Open CSA TCs?” Each
resource must be associated with a specification, and each specification must
be associated with a single Technical Committee. Technical Committees can
refer to each other’s work by incorporating a reference, but they cannot
contribute to, or alter that work.
Regards,
Mary
From: Patil, Sanjay
[mailto:]
Sent: Monday, October 01, 2007 2:18
AM
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
