DocumentID: ECMA-376/Part2/AnnexB
Title: ECMA-376, Part2: Annex B. Pack URI
Extracted-From: ECMA-376 Office Open XML File Formats, 1st Edition / December 2006
Warning: Coverted to HTML format by a script known to have bugs

• Next: Annex C. ZIP Appnote.txt Clarifications
• Table of contents: Table of contents
• Previous: Annex A. Resolving Unicode Strings to Part Names

Annex B: Pack URI

A package is a logical entity that holds a collection of parts. This Open Packaging specification defines a way to use URIs to reference part resources inside a package. This approach defines a new scheme in accordance with the guidelines in RFC 3986.

The following terms are used as they are defined in RFC 3986: scheme, authority, path, segment, reserved characters, sub-delims, unreserved characters, pchar, pct-encoded characters, query, fragment, and resource.

B.1 Pack URI Scheme

RFC 3986 provides an extensible mechanism for defining new kinds of URIs based on new schemes. Schemes are the prefix in a URI before the colon. [Example: "http", "ftp", "file" end example] This Open Packaging specification defines a specific URI scheme used to refer to parts in a package: the pack scheme. A URI that uses the pack scheme is called a pack URI.

The pack URI grammar is defined as follows:

pack_URI  = "pack://" authority [ "/" | path ]

authority = *( unreserved | sub-delims | pct-encoded )

path = 1*( "/" segment )

segment = 1*( pchar )

unreserved, sub-delims, pchar and pct-encoded are defined in RFC 3986

The authority component contains an embedded URI that points to a package. The package implementer shall create an embedded URI that meets the requirements defined in RFC 3986 for a valid URI. [M7.1] §B.3 describes the rules for composing pack URIs by combining the URI of an entire package resource with a part name.

The package implementer shall not create an authority component with an unescaped colon (:) character. [M7.4] Consumer applications, based on the obsolete URI specification RFC 2396, might tolerate the presence of an unescaped colon character in an authority component. [O7.1]

The optional path component identifies a particular part within the package. The package implementer shall only create path components that conform to the part naming rules. When the path component is missing, the resource identified by the pack URI is the package as a whole. [M7.2]

In order to be able to embed the URI of the package in the pack URI, it is necessary either to replace or to percent-encode occurrences of certain characters in the embedded URI. For example, forward slashes (/) are replaced with commas (,). The rules for these substitutions are described in §B.3.

The optional query component in a pack URI is ignored when resolving the URI to a part.

A pack URI might have a fragment identifier as specified in RFC 3986. If present, this fragment applies to whatever resource the pack URI identifies.

[Example:

Example B--1. Using the pack URI to identify a part

The following URI identifies the "/a/b/foo.xml" part within the "http://www.openxmlformats.org/my.container" package resource:

pack://http%3c,,www.openxmlformats.org,my.container/a/b/foo.xml

end example]

[Example:

Example B--2. Equivalent pack URIs

The following pack URIs are equivalent:

pack://http%3c,,www.openxmlformats.org,my.container

pack://http%3c,,www.openxmlformats.org,my.container/

end example]

[Example:

Example B--3. A pack URI with percent-encoded characters

The following URI identifies the "/c/d/bar.xml" part within the "http://myalias:pswr@www.my.com/containers.aspx?my.container" package:

pack://http%3c,,myalias%3cpswr%40www.my.com,containers.aspx%3fmy.container
/c/d/bar.xml

end example]

B.2 Resolving a Pack URI to a Resource

The following is an algorithm for resolving a pack URI to a resource (either a package or a part):

1. Parse the pack URI into the potential three components: scheme, authority, path, as well as any fragment identifier.
2. In the authority component, replace all commas (,) with forward slashes (/).
3. Un-percent-encode ASCII characters in the resulting authority component.
4. The resultant authority component is the URI for the package as a whole.
5. If the path component is empty, the pack URI resolves to the package as a whole and the resolution process is complete.
6. A non-empty path component shall be a valid part name. If it is not, the pack URI is invalid.
7. The pack URI resolves to the part with this part name in the package identified by the authority component.

[Example:

Example B--4. Resolving a pack URI to a resource

Given the pack URI:

pack://http%3c,,www.my.com,packages.aspx%3fmy.package/a/b/foo.xml

The components:

<authority>= http%3c,,www.my.com,packages.aspx%3fmy.package

<path>= /a/b/foo.xml

Are converted to the package URI:

http://www.my.com/packages.aspx?my.package

And the path:

/a/b/foo.xml

Therefore, this URI refers to a part named "/a/b/foo.xml" in the package at the following URI: http://www.my.com/packages.aspx?my.package.

end example]

B.3 Composing a Pack URI

The following is an algorithm for composing a pack URI from the URI of an entire package resource and a part name.

In order to be suitable for creating a pack URI, the URI reference of a package resource shall conform to RFC 3986 requirements for valid absolute URIs.

To compose a pack URI from the absolute package URI and a part name, the following steps shall be performed, in order:

1. Remove the fragment identifier from the package URI, if present.
2. Percent-encode all percent signs (%), question marks (?), at signs (@), colons (:) and commas (,) in the package URI.
3. Replace all forward slashes (/) with commas (,) in the resulting string.
4. Append the resulting string to the string "pack://".
5. Append a forward slash (/) to the resulting string. The constructed string represents a pack URI with a blank path component.
6. Using this constructed string as a base URI and the part name as a relative reference, apply the rules defined in RFC 3986 for resolving relative references against the base URI.

The result of this operation will be the pack URI that refers to the resource specified by the part name.

[Example:

Example B--5. Composing a pack URI

Given the package URI:

http://www.my.com/packages.aspx?my.package

And the part name:

/a/foo.xml

The pack URI is:

pack://http%3c,,www.my.com,packages.aspx%3fmy.package/a/foo.xml

end example]

B.4 Equivalence

In some scenarios, such as caching or writing parts to a package, it is necessary to determine if two pack URIs are equivalent without resolving them.

The package implementer shall consider pack URIs equivalent if:

1. The scheme components are octet-by-octet identical after they are both converted to lowercase; and
2. The URIs, decoded as described in §B.2 from the authority components are equivalent (the equivalency rules by scheme, as per RFC 3986); and
3. The path components are equivalent when compared as case-insensitive ASCII strings.

[M7.3]