[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Comments on AIR WD 015
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]