Comments on AIR WD 015

[Peter Niblett <peter_niblett@uk.ibm.com>]

Hi. I have read through the AIR. I think it will be very helpful to have a
consistent approach to naming, but I do have a number of comments on the
document.

220. Definition of an Artifact. Is a URN or Namespace URI considered to be
an artifact? They aren't mentioned in the definition

227-229     . What is the purpose of the Artifact Name definition? I could
not see where it is used, and the document contains a large number of
"name" concepts (Artifact Identifier, Artifact Name, Filename, Structured
Name, Product, Descriptive Name) so it would be helpful to remove one.

271. Many Web services specifications include WSDL files. Could we have an
artifact type for them?

328-329. Line 328 talks about ArtifactIdentifier, but 329 contains the
words artifactName: [descriptive name], which looks wrong to me. I would
have expected it to say artifactIdentifier: [as defined in section 5]

336. Does productVersion always include the leading letter v (i.e. v1.0),
or never include it, or is it optional? The syntax given at 336 and 643
doesn't seem to permit the v, yet the examples in 686 include a v.

336 (and 643). Why is the period and minor value optional? All examples I
have seen include the minor value even if it is zero, e.g. 1.0. It would
make things more consistent if they were mandatory.

374. Why has the use of underbar been prohibited in a product name? We use
it today in WSN, e.g. ws_base_notification. The trouble with mixed case is
that we would end up with three consecutive upper case letters, e.g.
WSBaseNotification which doesn't look good, or we have to artificially
lower the case of the B, i.e. WSbaseNotification, which again looks odd. I
understand there might be a concern about mixing hyphen and underbar in an
identifier, but I think that looks ok: ws_base_notification-1.3-spec-pr-01

393. This line says that Stage may be omitted for schemas, but MUST be
included for all other types. Since the list of types is not exhaustive
this seems a bit harsh (for example the exemption for schemas should apply
also to WSDL). Could we replace this with a list of types for which the
Stage MUST be included (Catalog, Conformance Criteria, Errata, Guidelines,
Profile, Requirements, Prose Specification)?

395 "A DescriptiveName must be included if no other metadata in included in
the ArtifactName". This seems to contradict 384 which says that the format
for ArtifactIdentifier is a structured name. If the intention is to allow
an ArtifactIdentifier to be either a Descriptive Name OR a Structured Name
(as implied by non-normative appendix B), then you should say this
explicitly at the start of 5.3 and not introduce the idea in the middle of
the definition of a structured name.

401. "A value of Form SHALL be used only for files, URLs, URNs.." Are there
any other kinds of artifact (if not, this sentence would seem to be
redundant)? Also it isn't clear whether Form is required for these kinds of
artifact or not. I would strongly oppose having to put .html onto a
Namespace URL. If it is a prose document that exists in multiple formats
(.pdf and .doc for example) are these considered to be distinct artifacts -
which would imply that their identifiers contain Form - or are they
different renderings of the same artifact - in which case they would have
presumably have an identifier without a Form.

414. Why is revision required for a filename but not for an
ArtifactIdentifier? I assumed that the reason for omitting it from the
ArtifactIdentifier is that you don't want to have to include it on an OASIS
standard - but then why require it for the filename? Also why is language
not allowed in a filename?  It would simplify things if 5.4.1 just said
that for a Spec or Prose document the Filename MUST be identical to the
ArtifactIdentifier (with a Form if not already included)

421. "The filename MUST be descriptive as to the document title". You don't
define the term 'Document Title'.  Can we just delete this sentence?

455/463. These sentences would seem to completely replace 5.4.1. Also if
you permit ArtifactIdentifiers for files to contain Form then these
sentences should say "including the literal period and Form" rather than
"followed by the literal period and form".

519. Please make it clear that .html is not required on a Namespace URL
(even though it is required to point at a RDDL document). Also to help
people construct their schema location and import statements, we should
have a convention that allows you easily to deduce the location from the
URI. At the moment some specs use the URL of the schema as the URI for the
namespace. Presumably we can no longer doing this if the Namespace URI has
to be the URL for the RDDL document (or have I misunderstood this?) So how
about saying that the pure URI (with no suffix) points at the RDDL, and the
URI with .xsd or .wsdl suffix points at the actual schema/wsdl document.

551. In order to avoid long and unwieldy URIs, the WSN and WSRF TCs use the
Technical Committee tree to contain their Namespace URIs and the
corresponding XML Schema and WSDL artifacts. We would wish to continue
doing this - and in any case some of these artefacts span multiple
products. It's not clear from the document whether this would be permitted
or not (the actual specs that own the artefacts live in the [product]
tree).

674. Appendix C is hard to read on the screen as it is rotated through 90
degrees. Does it have to be like this?

686. The examples talk about Part, but this isn't mentioned elsewhere in
the document.

Questions from your questionnaire on which I have an opinion...

3. Should hyphen be permitted in a Descriptive Name?  Yes
4. Should we reverse the order of stage and artifact type? No. Type and
Revision naturally fit together (wd-03)
5. Should schemas use structured names? No. I would like to keep the schema
name in step with the namespace URI, with the filename as the last node in
the URI. I also want to keep the URIs simple.
6. Are the requirements for ArtifactIdentifier confusing with respect to
file names? Yes. See my comments above. I think they should be identical
for prose documents (subject to the discussion about Form)
10. Examples. Some more would be useful
11. Additional artifact types? Yes (WSDL)
12. Is the grammar useful? Yes.


Peter Niblett
WS-Notification co-chair