Advisory 00002: URI/IRI References Among Package Parts - Follow-Up Analysis

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

There is some lengthy material collected in a provisional analysis at 
<https://tools.oasis-open.org/version-control/svn/oic/Advisories/00002-subdoc_trailing_slash/trunk/description.html>

That may be almost good enough by itself.

I can narrow this to the case at hand, referencing with trailing "/"

The answer is the trailing slash is required in order to resolve to an entry of that exact form in the manifest:full-path for a <manifest:file-entry> that provides a sub-document manifest:media-type value.

 - Dennis

PS: The use of "./" at the front of a relative IRI has nothing to do with whether or not a subdocument is being referenced, unless that is the entire IRI and the intention is to refer to the subdocument of which the referencing file is an immediate part.  Otherwise, the use of the "./" as a prefix in a relative reference is unnecessary unless the path segment immediately after that prefix has a ":" in its name.

MORE DETAILS

 1. SINGLE FILES

For all single files that are parts in the package, the package-root relative name is determined by the manifest:full-path attribute in the <manifest:file-entry> element for that package file.  

That manifest:full-path attribute for a single file in the package neither begins nor ends with "/".  It is not an IRI.  That is, it doesn't have a scheme part and there are no path segments that are empty or that have only "." characters in the segment name.  The filename in the Zip Package and the manifest:full-path attribute in the manifest should be identical.  The separator of path segments is always "/".  

The nature of a single file (when uncompressed) is specified by the manifest:media-type attribute of the same <manifest:file-entry> element.

The single files case is easy.  The formulation of relative references to such a file part is also depending on how many of the leading segments the referencing part has in common between its full-path name and the target full-path name.

 2. SUBDOCUMENTS

When a subdocument consists of multiple single files in some compound document organization, there are two two differences from the single-file case.

First, all of the actual files that are part of the subdocument exist in the package as files, each with their own full-path and media-type attributes in their manifest:full-path entries.  They are technically no different than any other single files in the package.

There are two other things these files have in common:

 a. They have a common set of leading path segments in the full-path names.

 b. The leading path segment has its own <manifest:file-entry> element, even though there is no such file in the package.  That file-entry establishes the leading path, which ends in "/", as the full-path name for a subdocument.  This subdocument <manifest:file-entry> also specifies the media-type that applies to the subdocument.  (This is the only reason a subdocument is needed, generally.)

For a file in the package to refer to the subdocument as an entity, rather than referring to one of its parts, the reference is to the subdocument manifest:full-path value, with its trailing "/".  The rules for relative reference are the same as for any entity having a <file-entry> and a manifest:full-path value.  The relative reference will also have the final "/".

 3. OBSERVATIONS

There can be subdocuments which have only single files as their parts.  Whether a producer refers to the subdocument or to the part depends on the purpose of the reference.  It may be important, even in this case, to reference the subdocument because its media-type is important to how the reference is to be understood.

The presence of a path separator at other than the end of a manifest:full-path entry does not mean that the full-path segment ending with that path separator is for a subdocument.  It is the presence of a <manifest:file-entry> with that full-path and a meaningful media-type that establishes a subdocument.  

The creation of <manifest:file-entry> elements having missing or empty manifest:media-type attributes for other leading path-segment prefixes that are not for subdocuments is unnecessary and just adds noise to the manifest.xml document.