Comments on "Artifact Identification Requirements 1.0", WD 15,30 June 2005

[Anne Anderson <Anne.Anderson@sun.com>]

- General: metadata items and either explicit or implies formats are
described in three places: 3.2 Name Component Definitions (says
"definitions are in the order used as name components"), 4. Required
Metadata for Artifacts, and 5.3 "Constructing Specific Artifact
Identifiers. Distinction between "artifactName" and "ArtifactIdentifier"
is not clear.  Why two things?  Suggestions:

o Do not distinguish between the artifact identifier and artifact name,
and use one name.  Both should match the filename under which the
artifact is stored, except that the file name should have
-[language]-[format] appended.  Section 5.3 suggests that perhaps the
file name also differs in having the [tcShortName}- prefixed.

o Combine Sections 4 and 5.3.  Remove "definitions are in the order used
as name components" from the introduction to section 3.2.

o Have a chart like Appendix C be the normative form, with the textual
descriptions as explanation of the chart.  The chart can indicate which
components are required for different types of identifiers (if there
needs to be a distinction), and can indicate when abbreviations
must/should/may be used and when not.

- Omission: Conventions for titles of documents.  Suggestion:
o All words except prepositions and internal articles capitalized.
o First line of title should be consistent with "product" plus "artifact
type" plus "descriptive name" followed by ProductVersion with no
preceding "v" or "V" or "Version".  Example:
XACML Profile for Role Based Access Control 2.0
o Second line of title should be
  non-abbreviated [Stage] [Revision] "," [Date]
where [Date] is in DD MMMM YYYY format: Example:
Working Draft 15, 30 June 2005

- p.1, line 2: Title: this is not a specification of "Requirements", but
an actual specification or guidelines.  Suggested title:
"Artifact Identification 1.0"

- p.1, line 5, Artifact Identifier: does not conform to Section 3.2
"Artifact Type" or Section 4 "Required Metadata for Artifacts".
Suggested Artifact Identifiers (depending on response to p. 1, line 2):
ArtifactIdentification-v1.0-spec-wd-15
ArtifactIdentificationRequirements-v1.0-req-wd-15
ArtificateIdentification-v1.0-guidelines-wd-15

- p.10, lines 264-271, Artifact Type: Appendix C lists several other
types, and these should be included here.  A more complete list, with
standard abbreviations, is better than a minimal list in this case.
Suggested additions:
o Conformance Tests - "tests" [or "ct"]
o Interoperability - "interop"
o Whitepaper - "wp"
o Test Assertions - "tests" [or "ta"]

- p.12, lines 329 and 343-344: "artifactName" and "descriptiveName" both
talk about using a "descriptive name".  "artifactName" itself is not
listed in Section 5.  Suggestion:
Change lines 328-329 as follows:
Each artifact MUST contain the ArtifactIdentifier consisting of the
following components expanded below:
artifactName:[tc]=[product]-[productVersion]-[artifactType]-[stage]-[descriptiveName]-[revision]

- p.13, lines 369-371, Common conventions: mention explicitly that
underscores MUST NOT be used with reason that they are hard to see in
browser links.  Suggestion: Change line 369 to say: "Within components,
spaces and underscores MUST NOT be used."

- p.13, line 390, ArtifactIdentifer: Why is "tcShortName" not part of
the ArtifactIdentifier?  This does not agree with p. 12, line 332.

- p.14, line 395, DescriptiveName: says "MUST be included if no other
metadata is included in the ArtifactName", yet earlier sections said
that other components such as "product", "version", etc. MUST be
included in the Artifact Name."  Suggestion:  Remove "if not other
metadata is included in the ArtifactName."

- p.14, line 401: should a URN contain a value for "Form"?  I can
understand a URL, since a physical document in some specific format will
be located there, but a URN is an identifier and not a pointer to a
specific document with a specific format.

- p.15, line 449: typo: "desriptiveName" should be "descriptiveName" in
two places.

- p.16, lines 480-485: is "document-id" the same as "descriptiveName"?

- p.16, lines 480 and 482: these two variations differ only in that the
first has "tc:[tc-id]" as the prefix, while the other has
"specification:[specification-id]" as the prefix.  It is hard to believe
that only tc-id is needed in one place, and only "specification-id" in
another.  Please justify.  Line 508 says "Form ONE (with the TC
identified with the Product) should be deprecated."  This suggests that
perhaps "specification:[specification-id]" was mistakenly omitted from
Form One.

- p.17, line 512: RFC 3122 is titled "Extensions to IPv6 Neighbor
Discovery", which is probably not an OASIS naming RFC.  Also, Normative
References does not include either [RFC 3121] or [RFC 3122] (or whatever
the second should be).

- p.18, line 578: append "other" to the specified path.

- p.19, line 585: [version] should specify whether "v2.0" or "2.0", etc.
is to be used for [version] here.  I recommend "2.0" form.

Anne
-- 
Anne H. Anderson             Email: Anne.Anderson@Sun.COM
Sun Microsystems Laboratories
1 Network Drive,UBUR02-311     Tel: 781/442-0928
Burlington, MA 01803-0902 USA  Fax: 781/442-1692