[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Link errors in latest CMIS 1.0 specification (CS 01)
Congratulations to members of the CMIS TC for a milestone
publication of CS 01. To judge from the number of prototype
implementations and references in the trade press, this CMIS
V1.0 Standard will be very popular (in relative terms). It
promises to be a very significant and widely read Standard.
For that reason, it's disconcerting to see a large number of
link errors in the published CS 01 version. I document some
of these link errors below. After examining this report (and noting
similar errors I've not reported): does the TC want to send
*this* version up for OASIS member ballot -- with these errors?
The 30(some) errors for link relation identifiers were
already reported to the TC in November 2009 but have not
been fixed.
Fixing the link errors would require (I think) multiple dozens
of textual edits to the specification. I'm not sure that
level of editing is allowed at CS stage once the document
has been submitted. It might depend upon the interpretation
of these assertions in the TC Process [#3]:
* "No part"
* "changed"
* "altered"
* "in any way"
"No part of the submission may be changed or altered
in any way after being submitted to the TC Administrator,.."
I see two general classes of link errors in CS 01:
* some 30 broken links involving URIs for link relation identifiers (I)
* links to [inner-document] locations incorrectly formed because
they have the wrong target - destination in a putative anchor (II)
If there's a TC resolve to fix these link errors in a subsequent
CS revision, I'll be happy to proof-read the text before TC approval.
Cheers,
- Robin Cover (OASIS)
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783
========= I. Links involving URIs for link relation identifiers ========
The CMIS 1.0 specification CS-01 still contains some 30 link
(Link Relation URI) errors that were reported on the CMIS TC
Comment List [cmis-comment@lists.oasis-open.org] on 5 Nov 2009
when they were spotted in CD-04.
It appears that the Comment Resolution Log document "Summary of
Public Comments and TC's Responses for CMIS Public Review,
October 23rd, 2009 - December 22nd, 2009" conflates and confuses
two separate issues:
1) incorrect link construction: links (HTTP scheme URI references)
which use the string '200901' in error for the intended '200908'
2) the early question of how best to handle the CMIS specific link
relations, viz., whether a new style of a namespace document
should be created for each of the named CMIS link relation
identifiers
These two topics are referenced in list messages copied out below,
respectively at [#1] and [#2]. In the former [#1], I identified
the 30-some URI/link errors. In the latter case [#2], I presented
a proposal for handling the CMIS link relation identifiers in a
manner analogous to HTTP scheme namespace URIs; this proposal was
later adopted by the TC, per the explanation in the Comment
Resolution log.
At the risk of being tedious and overly pedantic, here's the
problem with incorrect link construction, which encodes the
URI (substring) element '200901' in error for the intended '200908'.
All 30+ occurrences are in these URIs used for the link relation
identifiers:
http://docs.oasis-open.org/ns/cmis/link/200901/acl
http://docs.oasis-open.org/ns/cmis/link/200901/allowableactions
http://docs.oasis-open.org/ns/cmis/link/200901/changes
http://docs.oasis-open.org/ns/cmis/link/200901/foldertree
http://docs.oasis-open.org/ns/cmis/link/200901/policies
http://docs.oasis-open.org/ns/cmis/link/200901/relationships
http://docs.oasis-open.org/ns/cmis/link/200901/rootdescendants
http://docs.oasis-open.org/ns/cmis/link/200901/source
http://docs.oasis-open.org/ns/cmis/link/200901/target
The link errors occur in each of the Word (.doc) format, PDF
format, and HTML format documents. The errors appear on different
line numbers (perhaps pages) because the Word and PDF format
documents (apparently) have different numbers of pages and line
numbers.
In all three document formats, the URIs are formatted as hyperlinks,
so there is considerable risk that readers using any of the
"copy link" gestures in common software tools will select/copy and
propagate the URI (string) errors found in the link text (e.g.,
"Copy Link Location" in Adobe Acrobat Reader, "Copy Hyperlink" in
MS Word, "Copy Shortcut" / "Copy Link Location" / "Copy Link Address"
in Web browsers). Using "rightClick-copy" is faster than using the
gesture "mouseDown-drag-mouseUp-copy" so we can expect readers
to propagate the errors in the link text.
Note that these incorrect links do *not* resolve under DNS+HTTP to
anything (HTTP status code 404 Not Found), whereas the corresponding
correct URI references (each with '/200908/' for '/200901/ )
will resolve meaningfully to the namespace document at the
root ( http://docs.oasis-open.org/ns/cmis/link/200908/ ), where
these "Link Relations:" are briefly explained. Viz., these
correct URIs behave as designed when dereferenced, per the proposal
in [#2] and our common OASIS Library practice for such identifiers:
http://docs.oasis-open.org/ns/cmis/link/200908/acl
http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions
http://docs.oasis-open.org/ns/cmis/link/200908/changes
http://docs.oasis-open.org/ns/cmis/link/200908/foldertree
http://docs.oasis-open.org/ns/cmis/link/200908/policies
http://docs.oasis-open.org/ns/cmis/link/200908/relationships
http://docs.oasis-open.org/ns/cmis/link/200908/rootdescendants
http://docs.oasis-open.org/ns/cmis/link/200908/source
http://docs.oasis-open.org/ns/cmis/link/200908/target
http://docs.oasis-open.org/ns/cmis/link/200908/typedescendants
Example errors: on my system, for the following Word/PDF format documents:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.doc
MD5: 499283d5bb718532273ba64f32d7962c
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.pdf
MD5: 981c601307e84ca3e46b4232a819b03d
I see examples like these:
Line 5040 (Word) and line 5042 (PDF)
Link text: http://docs.oasis-open.org/ns/cmis/link/200901/allowableactions
Display text: http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions
Line 5047 (Word) and line 5049 (PDF)
Link text: http://docs.oasis-open.org/ns/cmis/link/200901/relationships
Display text: http://docs.oasis-open.org/ns/cmis/link/200908/relationships
Line 5053 (Word) and line 5055 (PDF)
Link text: http://docs.oasis-open.org/ns/cmis/link/200901/source
Display text: http://docs.oasis-open.org/ns/cmis/link/200908/source
[... etc]
Grep (though perhaps imprecise) reports thirty (30) of these
kinds of link errors in CMIS v1.0 CS 01. Other examples appear in
(Word) at lines 5060, 5067, 5073, 5085, 5322, 6412, 7219-1720, 7561,
8849, 8851, 8853, 8854, 8991, 8993, 8995, 8996, 9136, 9138, 9140,
9141, 9142... (etc)
========= II. Links with incorrect/malformed link targets ========
I here identity 15 or so; there are others.
A) Line 2423 (Word) contains a link associated with the phrase
"Optional Capability" where the link target is a location on
an editor's local machine:
http://docs.oasis-open.org/cmis/Documents%20and%20Settings/
rmcveigh/My%20Documents/Draft%2061/Content-streams%20are%20NOT%20exposed%20
through%20this%20relational%20view.%20However,%20a%20
Repository%20MAY%20support%20full-text%20indexing%20of%20Content%20St
B) Line 75 [73-75] in Word has an incorrect link for
"See section: 2.2.3.1 getFolderTree". The section labeled
"getFolderTree" is actually 2.2.3.3, and the link on line
75 actually takes the reader to the wrong location (i.e., to
Section '2.2.3.2 getDescendants').
C) Line 2108 (Word) in Section '2.1.9.4.1 Checkout' -- The text
reads "A new version of a versionable Document object is created
when the LINK:[checkIn] service is invoked on the Private
Working copy". The link for "checkIn" terminates at Line 3988,
Section '2.2.7.1 checkOut'. See for comparison the HTML format
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_checkOut
But it seems clear that the link for "checkIn" should terminate at
Section '2.2.7.3 checkIn' (Checks-in the Private Working Copy document)
(i.e., in the HTML version
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_checkIn
D) Line 2276 (Word) on page Page 65, the text reads "In this
relational view a Virtual Table is implicitly defined for
each queryable Object-Type defined in..." The text has a link for
"queryable". Clicking this link [#_Attributes_common_to] takes
the reader to line 2064 -- where no information about "queryable"
is provided. The HTML version suggests a badly placed anchor:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Attributes_common_to
E) Line 280 (Word), in Section '2.1.3 Object-Type', page 16, the text
reads "While a repository MAY define additional object-types
beyond the CMIS Base Object-Types, these..." where we have a link
to 'CMIS Base Object-Types'. Following this link leads to a blank
portion of the document on page 59, just following line 2064, at
the end of the Section '2.1.8.3.2 AllowableActions & Permission
Mapping', preceding Section '2.1.9 Versioning'. Why? Nothing
in Section 2.1.8.3.2 seems to explain 'CMIS Base Object-Types',
which are however, explained in Section '2.1.2 Object'. The HTML:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_CMIS_Base_Object-Type
F) Line 298 (Word) on page 17, similar to the link error in "E)" --
the text says "An object-type definition includes a set of
object-type attributes (e.g. Fileable, Queryable, etc.)" and
there's a link for 'object-type attributes' that leads to line
2064 (page 59) at the end of Section '2.1.8.3.2
AllowableActions & Permission Mapping'. This link destination
isn't particularly useful in understanding 'object-type attributes'.
The intended destination is apparently Section '2.1.3.2 Object-Type
Attributes' at line 316. See the corresponding HTML
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Object-Type_Attributes
G) Line 178 (Word) the text reads "Whether or not an object is
file-able is specified in its object-type definition." with a
link for "object-type definition." The link sends the reader
to line 1695 in the Section '2.1.8 Access Control'. See the HTML:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Object-Type
H) Lines 446-447 (Word) on page 20, the text reads: 'whencheckedout:
The property value MUST only be update-able using a "private
working copy" Document.' The link for "private working copy"
leads to a destination [#_Versioning], which appears as an anchor
in the document just preceding Section "2.1.9 Versioning".
One expects the link for "private working copy" to terminate at
(e.g.,) Section "3.10.3 Document Private Working Copy (PWC) Entry"
(Line 8965, page 204). See the HTML link expression:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Versioning
I) Lines 9794-9795 (Word) in Section '5.1.5 CMIS ACL': the mailto:
link (URI) appears to be malformed [it says: "mailto:OASIS";],
and the candidate addressee nominated in the visible display text
("cmis@lists.oasis-open.org") would fail in the general case
because someone sending email to that email address would need
to be authorized as a TC member to post to the member-only mailing
list. Any such mailing list is deactivated when the TC closes.
A better candidate would be: tc-admin@oasis-open.org. Similarly
in (Word) lines 9761, 9726, 9693, 9660.
J) Line 3133 (Word) the text reads: "<Array> Object-Types: The
hierarchy of Object-Types defined for the Repository." For the
link 'Object-Types', a reader is led to the location in
Section '2.1.8 Access Control', line 1695. See the HTML link:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Object-Type
K) Lines 3971-3972 (Word) the text has "<Array> changeEvents: A
collection of CMIS objects that MUST include the information
as specified in 2.1.11.3." Following the link for "as specified in"
seems to lead the reader to the top of the document rather than
to Section 2.1.11.3. See the HTML:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Schema_Elements_1
L) Line 3109 (Word) text reads: "Description: Returns the set
of descendant Object-Types defined for the Repository" where the
link for "Object-Types" leads to Section '2.1.8 Access Control'.
M) Line 2990 (Word) at the text "The operation is attempting to
perform an action on a non-current version of a..." we have a link
for "a non-current version". This link leads to a destination
in a blank document region following line 2064. HTML link:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Versioning
------ / stopped checking ------
Also (misc):
NS Documents: it appears that the document titles are incorrect
for two of the five XML namespace documents (messaging, link):
Content Management Interoperability Services Core
http://docs.oasis-open.org/ns/cmis/core/200908/
Content Management Interoperability Services RestAtom
http://docs.oasis-open.org/ns/cmis/restatom/200908/
*(sic!) Content Management Interoperability Services Core
-->> Content Management Interoperability Services Messaging
http://docs.oasis-open.org/ns/cmis/messaging/200908/
Content Management Interoperability Services WS
http://docs.oasis-open.org/ns/cmis/ws/200908/
*(sic!) Content Management Interoperability Services Core
-->> Content Management Interoperability Services Link Relations
http://docs.oasis-open.org/ns/cmis/link/200908/
================================= Notes:
[#1] Incorrect link construction: '200901' error for '200908'
Archived at:
http://lists.oasis-open.org/archives/cmis-comment/200911/msg00000.html
Date: Thu, 5 Nov 2009 17:05:19 -0500 (EST)
From: Robin Cover <robin@oasis-open.org>
To: CMIS Comment List <cmis-comment@lists.oasis-open.org>
Subject: HREF values in Link Relation URIs, etc
Message-ID: <Pine.LNX.4.64.0911051655470.2357@fs00.ma0.oasis-open.net>
In the CMIS Public Review draft (CD 04) at
http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html
I noted several HTML links where the anchor HREF attribute values are
different than the anchor element content, viz., the underlying
HTML code in the HREF value appears to be incorrect, while the
display text is apparently correct.
Actually, this appears not to be a root HTML problem, but a defect in
the editable source (.doc) from which HTML and PDF were apparently
generated.
Perhaps 30 or more of these, for example, in the section
"CMIS Specific Link Relations":
[a href="
http://docs.oasis-open.org/ns/cmis/link/200901/allowableactions
"]
http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions
etc.
test:
$ grep -c 200901 cmis-spec-v1.0.html
31
-rcc
======================================================================
[#2] How best to handle the CMIS specific link relation identifiers
Archived at:
http://lists.oasis-open.org/archives/cmis/200911/msg00011.html
http://lists.oasis-open.org/archives/cmis/200911/msg00012.html
Date: Fri, 6 Nov 2009 11:36:54 -0500 (EST)
From: Robin Cover <robin@oasis-open.org>
To: Al Brown <albertcbrown@us.ibm.com>
Cc: Mary McRae <mary.mcrae@oasis-open.org>, cmis@lists.oasis-open.org,
Robin Cover <robin@oasis-open.org>
Subject: Re: Fw: [cmis-comment] HREF values in Link Relation URIs, etc
Message-ID: <Pine.LNX.4.64.0911061111120.2357@fs00.ma0.oasis-open.net>
[Al Brown said]
> How should we handle the CMIS specific link relations [...]
> Should a new style of a namespace document be created for each [...]
At Mary's request, I have formulated for Al Brown a proposal for
handling of the ten (eleven/twelve) URIs at the DNS+HTTP level
so that the URIs:
a) have some meaningful representation returned to an HTML agent
when they are dereferenced, as we expect for HTTP scheme URIs
b) are handled as non-information resources (viz., distinguished
in processing from typical 'information resources' [1]; thanks
to the CMIS TC, a key feature enabling server-level support
has already been accounted for by the decision to utilize the
CMIS TC's /ns/ path element, which allows URI rewrites using
existing machinery
Al's suggestion to use something like a "new style of a namespace
document" is precisely what I thought of as a solution with
I created a news story for the CMIS public review draft, and
realized (yikes!) that the link relation URIs don't resolve [2].
If we understand a namespace to be fundamentally a "space of
names", then it's not too difficult to see the analogy to XML
namespaces and namespace documents. The root URI for the
collection of CMIS link relation identifiers is:
http://docs.oasis-open.org/ns/cmis/link/200908/
and each of the CMIS-specific link relations matching a
string identifier (URI) is a name in the hierarchical space
below /ns/cmis/link/200908/.
If a namespace document documents a namespace, then, by
analogy, a similar informative document (as an information
resource) can live at the end of the CMIS-specific link
relation URIs. Similar to the use of a single namespace
document to document several related URIs [3], a single
document could be used to document the key facts about
the CMIS-specific link relation URIs (associated
specification, spec owner(s), date, purpose, etc).
This analogy is (I think) consistent with an update I
made in August to the OASIS Naming Guidelines [4], clarifying
that use of the /ns/ path element seems like a reasonable
solution for "namespace related" URIs for collections of
named properties, functions, dialects, faults, actions,
and other message types as non-information resources.
Cheers,
- Robin Cover
[1] OASIS Naming Guidelines, non-information resources
http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingCommentaryV08.html#information-resources
[2] http://xml.coverpages.org/ni2009-10-30-a.html#Restful-AtomPub-section3
see the enumertion at
"In addition, several 'CMIS Specific Link Relations' are defined: [...]
[3] namespace document used to document collections of URIs
I've seen several conventions in W3C specs for handling
these kinds of special URIs, and some similar practices at
OASIS have been used. Here are the first examples I thought of:
** W3C property/relationship URIs
NS URI http://www.w3.org/2005/08/addressing
[WS-Addressing 1.0 Namespace]
with derivations
http://www.w3.org/2005/08/addressing/anonymous
[Web Services Addressing URI]
http://www.w3.org/2005/08/addressing/none
[Web Services Addressing URI]
http://www.w3.org/2005/08/addressing/unspecified
[Web Services Addressing URI]
** OASIS specs with action URIs
NS URI http://docs.oasis-open.org/ws-rx/wsmc/200702/
with
http://docs.oasis-open.org/ws-rx/wsmc/200702/fault
http://docs.oasis-open.org/ws-rx/wsmc/200702/MakeConnection
[4] use of /ns/ path for non-information resources
"...named properties, functions, dialects, faults, actions, other
message types as non-information resources"
http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingV08.html#uri-collision
=====================================================================
[#3] Changes/alterations to a Committee Specification
3.4 Approval of an OASIS Standard
http://www.oasis-open.org/committees/process-2009-07-30.php#OASISstandard
"No part of the submission may be changed or altered in any way
after being submitted to the TC Administrator, including by
Errata or corrigenda. Errata, corrigenda or other changes to a
Committee Specification are not permitted after its submission
for OASIS Standard approval; if changes are required the
Committee Specification must be withdrawn by the TC, edited,
re-approved as a Committee Specification, and then may be
resubmitted as a proposed OASIS Standard..."
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]