[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [cmis] Link errors in latest CMIS 1.0 specification (CS 01)
I applaud Robin's commitment to ensuring the spec of is of the highest quality and agree that the problems should be addressed. That said, there is no way to do so without drawing the current OS submission and upcoming ballot. The process would involve fixing the problems, approving the new iteration as a Committee Draft, agreeing that no substantive changes were made, requesting CS approval/OS submission ballots, and then resubmitting for OS upon successful completion of those ballots.
Regards,
Mary
Mary P McRae
Director, Standards Development
Technical Committee Administrator
OASIS: Advancing open standards for the information society
email: mary.mcrae@oasis-open.org
web: www.oasis-open.org
twitter: @fiberartisan #oasisopen
phone: 1.603.232.9090
Standards are like parachutes: they work best when they're open.
On Apr 5, 2010, at 11:30 AM, Robin Cover wrote:
> 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..."
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail. Follow this link to 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]