OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

sdd message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [sdd] Re: Request for Committee Specification Ballot: SDD


Robin,

I am at the OASIS Symposium with Mary. I'll try to sit down with her and go through these issues.

Apologies for any mismatches. As Mary, our specification editors and I (and I'm sure many other people) can attest, this process of just getting all the URIs (etc.) right can be downright brutal.

I appreciate your taking the time to work on this and point out discrepancies. I'm sure we'll find a way to resolve the issues.

Regards,
Brent

Brent A. Miller
Senior Technical Staff Member
Lead Architect, Autonomic Computing
IBM Corp.
Tel. 919-543-6959 (TIE 441)

"In theory, there is no difference between theory and practice. But, in practice, there is."
-- Jan L.A. van de Snepscheut


Robin Cover <robin@oasis-open.org>

04/29/2008 03:19 PM

To
SDD TC List <sdd@lists.oasis-open.org>
cc
Mary McRae <mary.mcrae@oasis-open.org>, Robin Cover <robin@oasis-open.org>
Subject
[sdd] Re: Request for Committee Specification Ballot: SDD






Owing to VPN (IP address) connection problems in Santa Clara, Mary McRae
asked me to upload files associated with "Solution Deployment Descriptor
Specification 1.0" (approved) Committee Draft 4, 8-April-2008, in
preparation for a Committee Specification ballot.

I cannot upload the files until I receive clarification from the
TC and/or Mary: the upload instructions forwarded to me are ambiguous
due to:

a) discrepancies between the instructions and the implications from
   the data themselves
b) apparent conflicts (discrepancies) in the data
c) incomplete instructions about desired filenames and file locations

It would be hazardous for me to guess at all the correct anwers, so
I am seeking clarification.

Lots of incorrect URIs: In addition, it appears to me that the
number of (apparent) discrepancies which could lead to errata or to a
failed CS ballot warrant re-examination of the data and/or instructions
made to TC Admin.  Since I do not have any official role as TC Admin,
I am not empowered to make changes to TC requests.  Furthermore, since we
to not "break links" (once a URI is published), there's too much risk
in (my) uploading resources to the incorrect location(s): the URIs
would become permanent.

=====================================================================
#1 Instructions for schema file upload implicitly contradict the
   URIs given in the canonical schema files
=====================================================================

The instructions request that the six XML schema files be unzipped
and installed in the /FullSchema/ and /CL1Schema/ directories. The
schema URIs in the schema files do not reflect the directory portion
in the paths

[quote from="TC instructions"]

* Full schema (set of XSD files in a ZIP) is at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27987/FullSchema.zip
  and the unzipped files are to be published at
  http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema
* CL1 schema (published for convenience; set of XSD files in a ZIP) is at
  http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27988/CL1Schema.zip
  and the unzipped files are to be published at
  http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema [/quote]

However, the XML schema files are at variance:

3x schema files in /FullSchema/ attest:
URL:            http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
schemaLocation  http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
schemaLocation  http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
URL: http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-deploymentDescriptor-1.0.xsd
URL: http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-packageDescriptor-1.0.xsd

3x schema files in /CL1Schema/ attest:
URL:            http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
schemaLocation: http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
schemaLocation: http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
URL: http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-deploymentDescriptor-1.0.xsd
URL: http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-packageDescriptor-1.0.xsd

Since we do not create arbitrary URI aliases, the TC needs to make a
clear choice, and (IMO) normalize/correct the URI references in all
specification materials.  Please confirm with Mary (that) WRT OASIS
rules that an "approved" CS cannot be emended, even "editorially"
for minor changes.

=====================================================================
#2  Similar to #1 above, the three RDDL (XML Namespace) documents
    have XML schema URIs lacking the directory components in the path
=====================================================================

XSD:
http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
XSD:
http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-deploymentdescriptor-1.0.xsd
XSD:
http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-packagedescriptor-1.0.xsd

Note in the "PackageDescriptor Namespace" document a typo:
*http://docs.oasis-open.org/sdd/nsv1.0/cd04/cd04-sdd-packagedescriptor-1.0.xsd
 (see HTML link code associated with the  display text
 "cd04-sdd-packagedescriptor-1.0.xsd")

=====================================================================
#3  Similar to the instructions, but at variance with the Schemas and
    RDDL document URIs, Specification Appendix A ("A. Schema File
    List") presents URIs with 1 directory components in the path
=====================================================================

From Appendix A

http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema/cd04-sdd-common-1.0.xsd
http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema/cd04-sdd-common-1.0.xsd
*http://docs.oasis-open.org/sdd/v1.0cd04/CL1Schema/cd04-sdd-deploymentDescriptor-1.0.xsd [typo]
http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema/cd04-sdd-deploymentDescriptor-1.0.xsd
http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema/cd04-sdd-packageDescriptor-1.0.xsd
http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema/cd04-sdd-packageDescriptor-1.0.xsd

* Note the typo in one of the URIs

=====================================================================
#4 'Previous Version: specification URIs on the cover page appear to
    be incorrect
=====================================================================

Whereas the "Previous Version:" URIs contain a substring 'pr01-r01',
the documents published in the OASIS Library for the preceding
spec version are different.  The most recent published version is
'pr01', and the URIs are as follows:

* http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.html site
* http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.doc site
* http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.pdf site

If the 'cd04' files are uploaded, the cover page "Previous Version:"
URIs will create status 404 errors when dereferenced:

http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.html 12 display
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.html link
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.doc 13 display
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.doc link
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf 14 display
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf link

We cannot break the existing URIs, and I have no authorization to
create (gratuitious) URI aliases, nor to seek out missing intermediate
documents (and publish them) -- should any such documents exist.


=====================================================================
#5  Similar to #4, the three RDDL (XML Namespace) documents attest
    URIs for resources that are missing (404)
=====================================================================

All three RDDL (XML Namespace) documents have:

*Prev:
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf
*Prev:
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf
*Prev
http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf

=====================================================================
#6  URIs published in the three RDDL (XML Namespace) documents for
    "Previous version:" [(Public Review, Revision 1)] schema files
    do not match any existing online resources
=====================================================================

The following schema file URIs in RDDL documents are published:

*Prev:
http://docs.oasis-open.org/sdd/v1.0/pr01/pr01-r01-sdd-common-1.0.xsd
*Prev:
http://docs.oasis-open.org/sdd/v1.0/pr01/pr01-r01-sdd-deploymentdescriptor-1.0.xsd
*Prev
http://docs.oasis-open.org/sdd/v1.0/pr01/pr01-r01-sdd-packagedescriptor-1.0.xsd

In fact, the most recent published schema URIs (they would be
("Previous version:" from the POV of CD04) are:

http://docs.oasis-open.org/sdd/v1.0/pr01/FullSchema/pr01-sdd-common-1.0.xsd
http://docs.oasis-open.org/sdd/v1.0/pr01/FullSchema/pr01-sdd-deploymentDescriptor-1.0.xsd
http://docs.oasis-open.org/sdd/v1.0/pr01/FullSchema/pr01-sdd-packageDescriptor-1.0.xsd

Dereferencing the URIs presented in the RDDL documents would result
in status 404 errors.

=====================================================================
#7 Incomplete information about RDDL file locations and filenames
=====================================================================

A. No instructions are given about the TC's preference (if any) for
   URIs to be associated with the RDDL namespace document files
   themselves.  By convention, we do not create directories (or
   files) corresponding to NS URIs themselves: we use URI rewrite
   rules to present a namespace document to a user (agent/client)
   when the NS URI is dereferenced, ensuring that the NS URI
   is retained in the browser address window.  By this means, we
   clearly associate the (visible) namespace URI with the namespace
   document which documents the namespace.

   Oddly, the published 'pr01' SDD specification has no namespace
   document(s) associates with the NS URIs, so convention is
   missing.  Absent any special request or preference from the TC,
   I would probably store the new namespace documents in the
   directory http://docs.oasis-open.org/sdd/v1.0/, OR create
   an alias in /v1.0/ with the actual file in /cd04/
   (http://docs.oasis-open.org/sdd/v1.0/cd04/) -- but the choice
   is not consequential.

B. The files embedded in the ZIP ('namespaces') are:

cd04-common-rddl-1.0.html
cd04-deploymentdescriptor-rddl-1.0.html
cd04-packagedescriptor-rddl-1.0.html

However, the upload instructions are silent about whether these
filenames represent a specific choice on the part of the TC.
If not, it might be clearer to follow the URI pattern used in
the other SDD spec resources, viz., to include the 'sdd'
naming component.  Thus:

sdd-cd04-common-rddl-1.0.html
sdd-cd04-deploymentdescriptor-rddl-1.0.html
sdd-cd04-packagedescriptor-rddl-1.0.html

Please clarify if any specific request is implied or of concern.

=====================================================================
#8 [Non-fatal] Example ZIP file missing from install list/instructions
=====================================================================

Appendix A ("A. Schema File List")

  [quote]
  "Example SDDs showing the use of the schema can be found at the
  following address.
  http://docs.oasis-open.org/sdd/v1.0/sdd-examples-v1.0.zip" [/]

No such file is currently installed, and is not referenced in the
install instructions.


=====================================================================
#9 [Non-fatal] XML Namespaces (not a showstopper for mere upload)
=====================================================================

* Section 1.7 "XML Namespaces" fails to identify the XML Namespaces;
  it only mentions three prefixes, but by rule, prefixes are
  insignificant. The critical namespace declaration is the
  HTTP scheme URI, and should be presented here.

"The XML namespaces defined as part of this specification are:
 - sdd-pd: stands for the package descriptor portion of the SDD
   namespace.
 - sdd-dd: stands for the deployment descriptor portion of the
   SDD namespace.
 - sdd-common: stands for the common (shared) types, elements
   and groups of the SDD namespace."

=====================================================================
#10 [FYI, Non-fatal] Missing documents references
=====================================================================

* Section 1.2 references a Primer, but the Primer '[SDDP]' does not
exist at the referenced URI(s):

[SDDP]                 Solution Deployment Descriptor Primer
http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.doc
http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.pdf
http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.html

* Section 1.2 references a Profile, but the Profile '[SDDSP]'
does not exist at the referenced URI(s):

[SDDSP]                 Solution Deployment Descriptor Starter Profile
http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.doc
http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.pdf
http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.html


- Robin Cover
  OASIS, Chief Information Architect

=========== Notes and References


[1] Sources:

http://www.oasis-open.org/committees/download.php/27964/sdd-spec-v1.0-cd04.doc
http://www.oasis-open.org/committees/download.php/27965/sdd-spec-v1.0-cd04.pdf
http://www.oasis-open.org/committees/download.php/27966/sdd-spec-v1.0-cd04-HTML.zip
http://www.oasis-open.org/committees/download.php/27987/FullSchema.zip
http://www.oasis-open.org/committees/download.php/27988/CL1Schema.zip
http://www.oasis-open.org/committees/download.php/28002/namespaces.zip

[2] Candidate URIs:

http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.doc
http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.pdf
http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.html
http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema
http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema

[3] (candidate) RDDL filenames as uploaded to Kavi in ZIP:

cd04-common-rddl-1.0.html
cd04-deploymentdescriptor-rddl-1.0.html
cd04-packagedescriptor-rddl-1.0.html


============= Upload request:

Brent Miller/Raleigh/IBM
04/17/2008 07:31 AM
To <mary.mcrae@oasis-open.org>
cc Subject
RE: Request for Committee Specification Ballot: SDDLink

Mary,

The specification has been updated to reflect its approval as CD04. Here's
the full updated information/request for CS ballot:

The OASIS SDD TC has approved moving the current CD04 specification and
schema draft forward for a Committee Specification vote. We understand
that you conduct this ballot.

SDD Public Review was held from January 18 - March 18, 2008. Two public
review comments were received (see the TC's "comments" e-mail archives);
details about these comments and their disposition can be found at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27940/SDD-PRComments.doc

The TC approved the PR01-R01 draft as CD04; this draft has no Substantive
Changes from the PR01 draft that was approved and underwent Public Review
(meeting minutes with the unanimous TC approval are at
http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27916/Meeting%20Minutes%20OASIS%20SDD%20TC%202008.doc
see the 03/27/2008 minutes).

Please publish the following documents on docs.oasis-open.org, according to the
URIs specified within the documents, and please initiate a ballot to approve
these as Committee Specification:

 *  Specification editable source (MS-Word): document is at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27964/sdd-spec-v1.0-cd04.doc
    and is to be published at
    http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.doc
 *  Specification PDF: document is at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27965/sdd-spec-v1.0-cd04.pdf
    and is to be published at
    http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.pdf
 *  Specification HTML: document (set of HTML files in a ZIP) is at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27966/sdd-spec-v1.0-cd04-HTML.zip
    and is to be
    published at
http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.html
 *  Full schema (set of XSD files in a ZIP) is at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27987/FullSchema.zip
    and the unzipped files are to be
    published at http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema
 *  CL1 schema (published for convenience; set of XSD files in a ZIP) is at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27988/CL1Schema.zip
    and the unzipped files are to be
    published at http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema
 *  The RDDL namespace documents are at

http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/28002/namespaces.zip
    ** The authoritative version of the specification is the MS-Word editable
source

    If you need any additional information, please let me know.

    Thank you!

Regards,
Brent

Brent A. Miller
Senior Technical Staff Member
Lead Architect, Autonomic Computing
IBM Corp.

==================================================


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  You may a link to this group and all your TCs in OASIS
at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]