This specification defines the XML Packaging format (XPackage), which allows multiple resources to be "packaged" into one entity. It defines an XML information set and XML syntax to describe the resources which are included in the package, their method of inclusion, and their relationships among one another. It allows for customization through extension and/or restriction.
This is an Open eBook Forum Working Draft for review by OeBF members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. The Publication Structure Working Group will not allow early implementation to constrain its ability to make changes to this specification prior to final release. It is inappropriate to use OeBF Working Drafts as reference material or to cite them as other than "work in progress".
This document has been produced as part of the OeBF Publication Structure Working Group and is intended to be the basis in part of the OeB Publication Structure 2.0. This publication is being reviewed by various experts in various companies and organizations, and is being developed with the needs of other specifications which are currently being developed by third parties in mind. Please send comments and questions regarding this document to garret@globalmentor.com.
The World Wide Web Consortium's [XML] specification has seen wide acceptance as a method of encoding textual content for display, for maintaining metadata, and for storing other forms of data. As many independent XML documents are increasingly being used in various situations that require these documents to interact in some fashion, there is becoming a need to maintain information in a standard form at a level above independent documents. Such information is necessary not only for illustrating to bundling applications the existence of relationships but also for defining the semantics of those relationships. This high-level group-related information includes:
This specification describes how a group of related files can be described as a single bundle or package, using XML as a storage format for package-related information. This specification does not dictate a particular physical bundling mechanism of the files identified in the package document, although several alternatives are recommended.
This packaging specification uses the [RDF] specification as a model for identifying resources and describing relationships among those resources. The data model borrows heavily from the model currently in use by the Open eBook Publication Structure version 1.0.1 [OEBPS], as well as some concepts in the IMS Content Packaging Specification [IMS Content Packaging] version 1.1.2.
The packaging syntax presented here in some instances mandates certain semantics, but in most cases allows expression of custom semantics through the extension of the general packaging syntax. The OEB Publication Structure 2.0 specification, for example, may attach certain semantics and behaviors a package processor must perform on relationships among XML documents and various XML namespaces, based upon the particular values expressed for those relationships.
<package> element. This specification defines the description of a package by means of the package description document. The term package is often used as a synonym for package resource.<RDF>, although this element is optional in certain contexts. The package description is usually contained within a package description document but may also appear in other XML documents. The package description instance may describe more than one package resource, although it may not describe any.This section is normative.
The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [IETF RFC 2119].
XML Package processing depends on [XML], [XBase], [XML Namespaces], [IETF RFC 2046], and [IETF RFC 2396] (as updated by [IETF RFC 2732]). XML Package processing may be facilitated through implementation of [RDF] and [XLink].
A package description is a conforming package description instance if:
An XML document is a conforming package description document if:
package.[TBD: XML InfoSet] [TBD: XML XLinkNaming]
An XML Package processor is any software module that can process and interpret some or all package description instances. Such a processor is conforming if:
An XPackage processor must be able to process and interpret all conforming package description documents and may be able to process and interpret other conforming package description instances. An XPackage processor may be a conforming RDF processor according to [RDF] in order to facilitate the processing of package description documents, although it is possible to process a package description document with no knowledge of RDF. An XPackage processor must be a conforming RDF processor if it processes general package description instances not contained in package description documents.
An XPackage processor may be a conforming XLink application according to [XLink] in order to facilitate the processing of package description documents, although it is possible to process a package description document with no knowledge of XLink. An XPackage processor may be a conforming XLink application if it processes general package description instances not contained in package description documents, but it must permit XLink attributes to sometimes appear as elements within the XLink namespace as required by the various possible serialized forms of RDF.
If an XPackage processor cannot process package description instances in general and can only proces package description documents, it may ignore unknown XML elements or attributes not defined or described in this specification. An XPackage processor must not fail to process a package description document because of unknown XML elements or attributes. If a package description document contains an XML element from another vocabulary, and that element defines an extension resource, an XPackage processor must process that resource and allow it to participate in relationships with other resources as mandated by this specification.
This section is informative
XPackage uses a subset of the [RDF] model and syntax for describing the relationships among the various resources that make up the package. While RDF can be expressed in a variety of forms, this specification in some areas restricts the syntax that can be used in a package description document in order both to clarify the package model and to ensure compatibility with other specifications such as [XLink]. All XPackage package description instances are valid RDF description instances, although the converse is not true.
The restricted syntax of a package description document allows an XPackage processor to process such a document with no knowledge of RDF, although such knowledge could facilitate processing. A processor must have knowledge of RDF to process a more general package description instance, however, because of its unrestricted serialization.
This specification assumes in its examples that the prefix rdf has been bound to the RDF namespace http://www.w3.org/1999/02/22-rdf-syntax-ns#.
The RDF model consists of three object types:
text/css, for example, may be a stylesheet property of an XML document resource.urn:oeb:examplepackage1-stylesheet1 (the subject) is a stylesheet (the property) of the XML document resource indicated by the URI urn:oeb:examplepackage1-chapter1 (the object)."RDF statements can be represented in one of several syntaxes. In the most general sense, RDF statements are described using the following syntax:
<rdf:Description> <rdf:subject rdf:resource="urn:oeb:examplepackage1-stylesheet1"/> <rdf:predicate rdf:resource="http://openebook.org/schema/Stylesheet"/> <rdf:object rdf:resource="urn:oeb:examplepackage1-chapter1"/> </rdf:Description>
A more common syntax would be to reference the object's URI using the RDF rdf:about attribute, and to reference the subject's URI using the RDF rdf:resource attribute on an XML child element in a separate namespace:
<rdf:Description rdf:about="urn:oeb:examplepackage1-chapter1"> <xmlprop:style rdf:resource="urn:oeb:examplepackage1-stylesheet1"/> </rdf:Description>
In this example, the item being described (the object) is identified using the RDF rdf:about attribute in an <rdf:Description> element, while the subject of the statement is referenced by the rdf:resource attribute of the child XML element. The stylesheet element in the package namespace serves as an identification of the statement predicate. It is assumed that the resource urn:oeb:examplepackage1-stylesheet1 is described elsewhere with its own <rdf:Description> description element or equivalent.
Note that the object being described above, urn:oeb:examplepackage1-chapter1, could itself be the subject of another statement. Its predicate could be expressed using an XML element from another vocabulary rather than the <rdf:Description> element.
RDF also provides various containers that allow resources to be grouped with corresponding semantics.
<rdf:Alt> element.<rdf:Bag> element.<rdf:Seq> element.[RDF] defines a general framework for defining resources and their relationships to one another, but does not itself prescribe the specific names or constraints for describing specific types of resources. It is the purpose of other specifications, such as this one, to define particular ontologies that describe certain information domains using the RDF model and syntax. A related specification, [RDF Schema], allows such an ontology to be described separately from its particular instance, in the same way a C++ class defines the allowed properties and constraints of a particular object type separately from any instance of that type.
This specification leverages RDF Schema for two purposes:
This specification assumes in its examples that the prefix rdfs has been bound to the RDF Schema namespace http://www.w3.org/2000/01/rdf-schema#.
XPackage uses RDF Schema to concisely describe the XPackage ontology. While a package description document must use a specific serialization defined by the XPackage XML Schema, the RDF statements contained in the package description document conform to the XPackage RDF Schema. Furthermore, general package description instances may use any valid RDF serializations as long as they conform to the XPackage RDF Schema.
RDF Schema also defines various properties which may be used with resources in general. These are mostly documentation-related properties such as rdfs:comment and rdfs:label. Some of these properties are necessary to replicate the semantics of other specifications. For example, rdfs:label allows the title of a stylesheet to be defined to replicate the use of the title attribute of [XML Style Sheets].
Such general properties conforming to [RDF Schema] may be used with any package description instance. When used with a package description document, these properties must appear as child XML elements of the resource being described.
RDF describes resources by their identifying URIs, but RDF by itself is insufficient to indicate the physical location of those resources. This specification therefore uses [XLink] to provide resource location information.
The restricted syntax of a package description document allows an XPackage processor to process such a document with no knowledge of XLink, although such knowledge could facilitate processing. Nevertheless, all referenced URIs must be processed in accordance with XML Base [XBase], as required by XLink.
As a more general package description instance allows a variety of serializations, a processor compliant with XLink must allow a variety of serializations of entities in the XLink namespace, including instances in which XLink entities that are normally attributes are expressed as elements.
XLink provides two types of syntax: simple links and extended links. XPackage only uses simple XLink references of a specific form and thus allows each XLink expression to remain valid RDF.
As a non-normative example, the description of urn:oeb:examplepackage1-chapter1 could also provide a location for the resource by using the following XLink syntax:
<rdf:Description rdf:about="urn:oeb:examplepackage1-chapter1"> <xpackage:location xlink:type="simple" xlink:href="chapter1.html"/> <xmlprop:style rdf:resource="urn:oeb:examplepackage1-stylesheet1"/> </rdf:Description>
XPackage uses MIME media types [IETF RFC 2046] to allow classification of the contents of a resource. This specification follows HTML 4 [HTML4] in employing the term content type to identify the MIME media type, in accordance with current usage, in order to distinguish it from the type of media for which the content is intended.
A package as an entity exists separately from any description. There are indeed an infinite number of packages that exist, most of which do not have any descriptions in any format. This section defines a model and syntax for describing a package by means of a package description document.
This section discusses the package description instance when it occurs only in one document, the package description document. However, the package description instance may be comprised of descriptions located in any appropriate XML document, and may even consist of descriptions in several XML documents. Such package descriptions that reach outside the package description document are discussed below in the section, "Package Description Instance". [TBD: write section]
In a package description document, the package description instance is contained within an element <description> defined in the package namespace http://openebook.org/namespaces/package/2001/. (Note that namespace prefixes are assumed to have been bound to the appropriate namespace elsewhere in the document. Namespace declarations will therefore not be included in these examples.) There is also an <RDF> element that encloses the RDF statements about the package resource and is defined in the namespace http://www.w3.org/1999/02/22-rdf-syntax-ns#. The enclosing <description> allows the package description instance to be grouped, transported, and identified as such. The enclosing <RDF> element identifies the package instance as compliant [RDF] so that it may be recognized as such by any RDF processor.
The following non-normative XML schema fragment illustrates the outermost elements of a package description document, <description> and <RDF>:
<xsd:element name="xpackage:description"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:RDF"/> <xsd:sequence> </xsd:complexType> </xsd:element>
The package description document allows the description of various resources, including any package resource and any related resources. Each resource, whether package resource or other resource, must be defined using similar syntax at the same hierarchical level in the XML document, as illustustrated by the following non-normative XML fragment:
<xpackage:description> <rdf:RDF> <xpackage:package> <--package resource description--> <xpackage:package> <xpackage:resource> <--package item description--> <xpackage:resource> <xpackage:resource> <--package item description--> <xpackage:resource> ... </rdf:RDF> </xpackage:description>
A package description document may contain only a package description fragment that does not describe a package resource. Such a package description document might be used, for example, to describe item resources along with their particular properties. A package description without a package resource is usually not useful for transport of items, however, as their is no information present to indicate which items should be included in any package archive.
Each resources described by a package description instance can be classified as a general resource, a general package resource, or an extension resource.
General resources are defined in a package description document by the XPackage <resource> element or by equivalent RDF type in a package description instance. General resources are usually supporting resources in the package, and usually each has its own physical location in a file system. If a general resource includes a manifest, it is also a package resouce.
Genereal resources may be represented using the <resource> element defined in the XPackage namespace. Each <resource> element describes a resource that may be referenced by any other resource as a resource property or in a package manifest or package organization. The following non-normative XML Schema fragment illustrates the content model of a <resource> element:
<xsd:element name="xpackage:resource"> <xsd:complexType> <xsd:sequence> <xsd:element ref="xpackage:manifest" minOccurs="0" maxOccurs="1"/> <xsd:element ref="xpackage:organization minOccurs="0" maxOccurs="1""/> <xsd:element ref="xmlprop:annotation" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:contentType" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:location" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:media" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:metadata" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:namespace" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:navigation" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:processing" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:script" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:style" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:unicode" minOccurs="0" maxOccurs="unbounded"/> <xsd:sequence> <xsd:attribute name="rdf:about" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
A <resource> element must identify the general resource using the rdf:aboutattribute. This attribute allows the general resource to be referenced from another resource property using the other resource's rdf:resource prpoerty attribute. The rdf:about attribute may contain the same content, a URI, as may the rdf:resource attribute. This URI is provided solely to authoritatively identify the item resource — it does not indicate the physical location of the item resource in a file system. For specifying the location of a resouce, see "Location".
The following non-normative example illustrates referencing an item resource both from another item resource and from an explicit package resource:
<xpackage:decription> <rdf:RDF> <xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter1"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-stylesheet"/> </rdf:Bag> </xpackage:manifest> </xpackage:package> <xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1"> <--item resource description--> <xmlprop:style rdf:resource="urn:oeb:examplepackage1-stylesheet"/> <xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-stylesheet"> <--item resource description--> <xpackage:resource> </rdf:RDF> </xpackage:description>
The above example describes two general resources, identified by the URIs: urn:oeb:examplepackage1-chapter1 and urn:oeb:examplepackage1-stylesheet. Both general resources are included in the general package resource manifest through use of the rdf:resource attribute. The latter resource, urn:oeb:examplepackage1-stylesheet, is specified to be a stylesheet of the former, urn:oeb:examplepackage1-chapter1, through use of the package <stylesheet> element.
Each <resource> element will usually contain several child XML elements such as <xmlprop:style>, each of which describe properties of the corresponding item resource. Each available package property is defined in the package namespace and described below under "Resource Properties". [TBD: update link]
A general package resource is a package resource that describes a loosly defined grouping of resources that does not have a strong identify as an indendent entity. A general package resource usually does not have special semantics as a resource other than as a grouping mechanism for the components of a package. Resources with strong identities should provide specific typing through use of a resource extension [TBD link].
A general package resource, like all package resources, must contain a manifest property. As it is a general grouping resource, a general package resource has no physical location and therefore must not contain a location property. Although described in the package description instance, which may be located in a package description document, the package resource and its corresponding package description document are distinct.
The <package> element provides for the package resource to be given an RDF identifier by use of the rdf:about attribute, as shown in the following non-normative XML schema fragment:
<xsd:element name="xpackage:package"> <xsd:complexType> <xsd:sequence> <xsd:element ref="xpackage:manifest"/> <xsd:element ref="xpackage:organization"/> <xsd:element ref="xmlprop:annotation" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:contentType" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:media" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:metadata" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:processing" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:namespace" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:script" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:style" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:unicode" minOccurs="0" maxOccurs="unbounded"/> <xsd:sequence> <xsd:attribute name="rdf:about" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
[TBD: do we want to force an a resource ID to be defined for the package?]
Each general package resource may contain any property as may a general resource, except for the location property. The following non-normative example shows a general package resource containing only the required manifest:
<xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <--package manifest contents--> </xpackage:manifest> </xpackage:package>
[TBD: modify, move, point to extension property] Note that while this non-normative content model restricts the types of children a <package> element may have, this specification makes no such restriction. The <package> element may include elements from other vocabularies as long as the child elements conform to [RDF]. Inclusion of elements from different vocabularies is encouraged as an abbreviated syntax for describing the RDF predicate of a statement in which the package is the RDF subject. This mechanism allows other specifications to extend the package description by using custom vocabularies from other namespaces. [TBD: add processor requirements]
A package description document may include resource definitions that use XML elements from a different vocabulary than that described by the package namespace. Such an extension resource may have any XML content that encodes valid RDF. An XPackage processor must process each extension and correctly assign to the resource properties defined in this specification, should that extension have any such properties. An XPackage processor must, if the extension contains a valid rdf:about attribute, associate that resource extension with any other resource that references it as the processor would do with any other item resource. An XML processor may provide other special processing beyond this specification based upon the contents of the extension.
The following non-normative example illustrates using an extension from the Annotea vocabulary to encode an annotation resource that may be referenced from an annotation property. The example assumes that the prefix annotea has been bound to the namespace http://www.w3.org/2000/10/annotation# in another part of the document:
<xpackage:description> <rdf:RDF> <annotea:Annotation rdf:about="urn:oeb:examplepackage1-chapter1-annotation"> <rdf:type rdf:resource="http://www.w3.org/2000/10/annotationType#Comment"/> <dc:creator>Jane Doe</dc:creator> <dc:date>2001-10-04T22:16Z</dc:date> <annotea:context>#xpointer(id("heading2")/p[2])</annotea:context> <annotea:body>Notice how boring this chapter suddenly becomes.</annotea:body> </annotea:Annotation> </rdf:RDF> </xpackage:description>
[TBD: add package resource extension example, such as for a QTI assessment]
XPackage defines several properties that may be associated with a resource. When included in a package description document, the properties must be defined using the given XML elements from the XPackage vocabulary. When included in a general package description instance outside of a package description document, these properties may be specified using any valid RDF serialization using the typical RDF combination of XPackage namespace and property name.
Resource properties can be classified according to their vocabulary, and this specification allows a variety of property vocabularies to be used. This specification defines three property vocabularies: the general resource vocabulary, the package property vocabulary and the XML property vocabulary. A resource may include custom properties through extension properties.
Besides the package properties defined by this specification, a resource may be extended through use of other properties from other vocabularies, each indicated by a namespace other than the package namespace. This extension may contain metadata for the item, as described in "Metadata". Each extension property must fully comply with [RDF] and may include an rdf:resource attribute. If an extension property provides a valid rdf:resource attribute, an XPackage processor must locate the reference resource in the extension property as it would for any other property in the package namespace, although it might not be aware of the particular semantics bound to the extension vocabulary.
[TBD: add example]
The following properties are defined in the XPackage vocabulary represented by the namespace http://openebook.org/namespaces/package/2001/ and may be be associated with any resource unless otherwise specified.
<xpackage:contentType>)A resource described in the package description instance may specify at most one media type as defined by [IETF RFC 2046]. Such a media type is specified using the XPackage <contentType> element, as illustrated by the following non-normative XML Schema fragment:
<xsd:element name="xpackage:contentType" type="xsd:string"/>
A PNG [TBD: reference] image, therefore, might declare its media type to be image/png using the syntax in the following non-normative example:
<xpackage:resource rdf:about="urn:oeb:examplepackage1-image1png"> <xpackage:location xlink:href="image1.png"/> <xpackage:contentType>image/png</xpackage:contentType> </xpackage:resource>
A package description document is itself a resource, although that resource is usually not described in the package document instance. In a case in which the package description document is described in the package description instance, or if it participates with other resources at an application level higher than the package description instance, it should take on the media type application/package-description+xml (see [IETF 3023]). [TBD: register media type] This media type applies only to the package description instance that appears in the package description document. This media type does not apply to any resource, including any item or package resource, that is described in the package description document, unless that resource is also a package description document.
If package description document represents some specialized form specific to some higher level application, it may take on a custom media type. That media type must comply with [IETF RFC 2046], should comply with [IETF 3023], and should include the suffix +package-description+xml. As a non-normative example, a description document for a library of books might use the media type application/library+package-description+xml, or application/x-library+package-description+xml if the media type has not been registered.
Any package resource defined should be assigned a media type that reflects the application-specific media type the package resource represents. Such a media type must comply with [IETF RFC 2046]. As a non-normative example, a package resource representing a library of books might use the media type application/library, or application/x-library if the media type has not been registered.
If a package resource does not represent some application-specific specialization of a package, that resource should be assigned the media type application/xpackage. If no media type is specified, the package resource takes on the application/xpackage media type by default.
The following non-normative package description document fragment illustrates a package resource which represents a fictitious library resource, using a fictitious media type of application/library that has, in this example, been registered:
<xpackage:description> <rdf:RDF> <xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:contentType>application/library</xpackage:contentType> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:oeb:examplepackage-book1"/> <rdf:li rdf:resource="urn:oeb:examplepackage-book2"/> <rdf:li rdf:resource="urn:oeb:examplepackage-book3"/> </rdf:Bag> </xpackage:manifest> <xpackage:organization> <rdf:Seq> <rdf:li rdf:resource="urn:oeb:examplepackage-book1"/> <rdf:li rdf:resource="urn:oeb:examplepackage-book2"/> <rdf:li rdf:resource="urn:oeb:examplepackage-book3"/> </rdf:Seq> </xpackage:organization> </xpackage:package> </rdf:RDF> </xpackage:description>
<xpackage:location>)A package description instance may specify the location of a particular resource describing the URI from which the resource may be obtained. In simple package configurations, this location is usually the name of the file in which the resource resides relative to the package description document.
A resource location uses the [XLink] namespace http://www.w3.org/1999/xlink to provide linking semantics to the location, specifically the XLink href property. The location is specified using xlink:href as a property of an item resource's location property, not as a property of the item itself. The location thus becomes the object of an [RDF] statement in which the item's location property is the subject and http://www.w3.org/1999/xlinkhref is the predicate.
A package description document that describes the location of a resource must do so using a <location> element in the XPackage namespace, in conjunction with an href attribute from the XLink namespace attached to the same element. The following is a non-normative XML Schema fragment that describes this element structure:
<xsd:element name="xpackage:location"> <xsd:complexType> <xsd:attribute name="xlink:href" type="xsd:anyURI" use="required"/> <xsd:attribute name="xlink:role" type="xsd:string"/> <xsd:attribute name="xlink:arcrole" type="xsd:string"/> <xsd:attribute name="xlink:title" type="xsd:string"/> <xsd:attribute name="xlink:type" fixed="simple"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="simple"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> <xsd:attribute name="xlink:show" fixed="none"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="none"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> <xsd:attribute name="xlink:actuate" fixed="none"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="none"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:complexType> </xsd:element>
Each <xpackage:location> element must conform to the XLink [XLink] specification, and must contain a valid value for the xlink:href attribute. The given schema fragment contains an xlink:type attribute with a fixed value of "simple"; when used in conjunction with such a schema, the explicit setting of the xlink:type attribute is optional, but must not take on any value other than "simple".
The location may also specify a link role, arcrole, and title as allowed by [XLink] through the use of the xlink:role, xlink:arcrole, and xlink:title attributes, respectively. When any of these attributes are used with the <xpackage:location>, they create properties of the location link, not of the resource in which the location is being defined.
An item resource specified in a package description document must have at most one location specified, although a general package description instance may have more. [TBD: link to package description instance section] An item resource may have no location specified if there exists no external representation of the resource, or if the processing application has adequate knowledge from the context to determine the item location at the time of processing.
The following is a non-normative example of using the <xpackage:location> element to specify the location of a resource:
<xpackage:description> <rdf:RDF> <xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter1"/> </rdf:Bag> </xpackage:manifest> </xpackage:package> <xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1"> <xpackage:location xlink:href="chapter1.html"/> </xpackage:resource> </rdf:RDF> </xpackage:description>
In the above example, the URI urn:oeb:examplepackage1-chapter1 uniquely identifies the item resource from an RDF standpoint, and allows the resource to be referenced from other resources in the package description instance. The location chapter1.html specifies where the resource physically resides — in this case, in a file named chapter1.html relative to the package document.
Non-RDF resources described in the package, including XHTML [XHTML] documents, will likely not reference references using their unique RDF identifying URIs. These resource instead usually reference the resource using what the referencing resource believes to be URI location of the referenced resource. Such referencing is usually accomplished using the XHTML <a> element, an [XLink], or some other URI-based location referencing scheme.
For any resource described in the package description instance that specifies a location, an XPackage processor must correctly resolve URI location-based references in other packages, providing the reference is made using a syntax understood by the XPackage processor to be such a reference. For such reference resolutions, the XPackage processor must make whatever normalizations necessary for the URIs being referenced, including, if needed, normalizing any references relative to a resource, normalizing the target URI in the package description document relative to the package description document, and normalizing relative to any XBase declarations. An XLink processor must conform to XML Base [XBase] when determining an absolute URI.
<xpackage:media>)A resource may provide one or more media descriptors to indicate for which media the given resource is intended. The media descriptor is semantically equivalent to that defined in HTML [HTML4]. Media descriptor values must be parsed according to the rules prescribed in [HTML4].
The media descriptor values allowed are the same as those defined in current and future versions of HTML, including the following non-normative list from [HTML4]:
screenttytvprojectionhandheldprintbrailleauralallA media descriptor is specified using the XPackage <media> element, as illustrated by the following non-normative XML Schema fragment:
<xsd:element name="xpackage:media" type="xsd:string"/>
Media descriptors may only be relevant to particular types of resources, but are especially valuable for stylesheet associations. The XPackage stylesheet association mechanism described in "Style" follow the semantics of [XML Style Sheets], which requires the ability to describe media to which a style should be applied. The following non-normative example illustrates specifying a stylesheet that might be applied on the screen and in print:
<xpackage:resource rdf:about="urn:oeb:examplepackage1-stylesheet1"> <xpackage:contentType>text/css</xpackage:contentType> <xpackage:media>screen</xpackage:media> <xpackage:media>printer</xpackage:media> </xpackage:resource>
Again following [HTML4], style resources that include internal descriptions of media-dependent variations (such as the CSS @media construct) may use a media descriptor value of all.
<metadata>)Metadata may be associated with package resources or item resources using the same syntax. This syntax includes two options for associating metadata: through native inline RDF property association, and through use of the package <metadata> element when metadata are inside some other resource.
The preferred form of metadata is that defined within a series of RDF statements. This allows the metadata to be directly included into the resource graph [TBD: define, or refer to RDFS] in a consistent way accessible to an RDF processor. Native RDF can be included using either internal or external syntax. Non-RDF metadata can also be associated with resources, but such associations must use the second, external syntax.
The package description instance, being an application of RDF, allows other RDF-based metadata to be natively integrated into the RDF instance using an inline syntax. Any RDF-based metadata ontology may be used, as long as standard RDF syntax is used to associate the various properties with a resource using RDF statements. Put another way, a package description document allows any valid RDF material to be located within the RDF <RDF> element, interspersed among the various package elements defined in this specification.
This specification does not prescribe or provide a normative description of any metadata ontology. A popular ontology for describing metadata is the Dublin Core [DC], [DC RDF/XML]. The following non-normative example assumes the Dublin Core namespace has been associated with the XML prefix dc, and provides Dublin Core metadata as RDF child elements of the resources being described — in this case, both the package resource and an item resource have metadata:
<xpackage:description> <rdf:RDF> <xpackage:package rdf:about="urn:oeb:examplepackage1"> <dc:creator>Garret Wilson</dc:creator> <dc:subject> <rdf:Bag> <rdf:li>Examples</rdf:li> <rdf:li>Specifications</rdf:li> <dc:subject>Examples</dc:subject> <xpackage:manifest> <--package manifest contents--> </xpackage:manifest> <xpackage:organization> <--package organization contents--> </xpackage:organization> </xpackage:package> <xpackage:resource> <dc:creator>Jane Doe</dc:creator> </xpackage:resource> </rdf:RDF> </xpackage:description>
If metadata are defined in a resource separate from the package description document, the metadata are associated through use of the package <metadata> element. This element is used when associating metadata to either a package resource or to an item resource, and is used regardless of the format in which the associated metadata are stored. The associated metadata resource must be an item resource defined elsewhere in the package description document as with any other item resource association.
The <metadata> element is shown in the following non-normative XML schema fragment:
<xsd:element name="xpackage:metadata"> <xsd:complexType> <xsd:sequence> <xsd:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/> <xsd:sequence> <xsd:attribute name="rdf:resource" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
Binding a metadata resource to another resource is accomplished by referencing the metadata resource using the rdf:resource attribute in exactly the same way as is done, for example, with resources included in the package manifest. The following non-normative example illustrates specifying that the resource urn:oeb:examplepackage1-rights provides package metadata. As with any other resource reference, such a reference defines neither the location of the resource nor any further information about its contents:
<xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <--package manifest contents--> </xpackage:manifest> <xpackage:metadata rdf:resource="urn:oeb:examplepackage1-rights"/> </xpackage:package>
Associating metadata defined in another resource to the package, as in the example above, is in fact a abbreviated forms of an RDF statement. This statement has the package as the RDF statement subject, http://openebook.org/namespaces/package/2001/metadata as the RDF statement predicate, and the metadata item resource as the RDF statement object.
<xpackage:processing>)A resource may provide processing information to indicate to an application specific rules under which processing should take place. This specification defines specifying processing instructions through use of a profile, but future versions of this specification may allow other processing information to be added.
A processing profile describes the properties of a hypothetical resource and indicates the level of support an application must give to actual resources in relation to those properties. The allowed profile properties are identical to the common resource properties, although that some properties (such as annotations) may not be appropriate for a profile. A resource may describe more than one processing profile.
One processing profile, for instance, may declare that the media type image/jpeg and the namespace http://www.w3.org/1998/Math/MathML are "required" but that the media type image/gif is "optional". (In the latter case, the package description instance may have provided a fallback for the specific resources with a media type of image/gif.)
A resource describes processing information by using the XPackage <processing> element. In this specification, processing information must be a profile described using the XPackage <profile> element, although future versions of this specification may allow other types of processing information. An XPackage processor may ignore processing information other than profiles and must continue processing the package description instance without error if unknown processing information is encountered.
A non-normative XML Schema fragment describing the processing profile appears below:
<xsd:element name="xpackage:processing"> <xsd:complexType> <xsd:sequence> <xsd:element name="xpackage:profile"> <xsd:complexType> <xsd:sequence> <xsd:element name="xpackage:support" type="xsd:string"/> <xsd:element ref="xmlprop:annotation" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:contentType" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:location" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:media" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xpackage:metadata" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:namespace" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:script" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:style" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="xmlprop:unicode" minOccurs="0" maxOccurs="unbounded"/> <xsd:sequence> <xsd:attribute name="xpackage:support" type="xsd:string" use="required"/> <xsd:attribute name="xpackage:level" type="xsd:string" use="optional" default="full"/> </xsd:complexType> </xsd:element> <xsd:sequence> </xsd:complexType> </xsd:element>
Each processing <profile> element must contain one support attribute. The support value should be one of the values listed below, and should be interpreted according to the following normative definitions:
While the above definitions indicate the meaning an XPackage processor should assign to certain support values, they do not imply any particular actions an application should take based upon those definitions. An XPackage-based application may, for instance, allow processing to continue even if a resource has a property unsupported by the application yet indicated as required in one of the resource's profiles.
If a package description instance uses a profile support property other than those listed here, the support value should be prepended with the characters x- to indicate a custom support value. An XPackage processor may ignore support values not included in this specification and must continue processing the package description instance if an unknown support value is encountered.
A processing profile may also indicate the level of processing that an application should give to the resource, indicated through the level attribute. The level value should be one of the values listed below, and should be interpreted according to the following normative definitions:
If a profile does not specify a level value, its level value is assumed to be full.
While the above definitions indicate the meaning an XPackage processor should assign to certain level values, they do not imply any particular actions an application should take based upon those definitions. An XPackage-based application may, for instance, allow processing to occur with full capabilities een if restricted is indicated, or may require that processing be restricted to a subset required by the application.
If a package description instance uses a profile level property other than those listed here, the level value should be prepended with the characters x- to indicate a custom level value. An XPackage processor may ignore level values not included in this specification and must continue processing the package description instance if an unknown level value is encountered.
The following non-normative example illustrates a package resource that requires processing of resources with the content type image/gif as optional. Processing of Unicode code points that make up the Hiragana and Katakana scripts are required, as is processing resources that are of content type text/css. The Unicode code points for superscript '2' (0x00B2) and subscript '2' (0x2082) are also required. Processing of resources that use the QTI namespace http://www.imsproject.org/xsd/ims_qti_rootv1p1 [QTI] is required, but the support of QTI is restricted according to some other application rules not specified here.
<xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <--package manifest contents--> </xpackage:manifest> <xpackage:processing> <xpackage:profile> <xpackage:support support="optional"/> <xpackage:contentType>image/gif</xpackage:contentType> </xpackage:profile> </xpackage:processing> <xpackage:processing> <xpackage:profile> <xpackage:support support="required"/> <xpackage:contentType>text/css</xpackage:contentType> <xmlprop:script>hiragana</xmlprop:script> <xmlprop:script>katakana</xmlprop:script> <xmlprop:unicode>[\u00B2,\u2082]</xmlprop:unicode> </xpackage:profile> </xpackage:processing> <xpackage:processing> <xpackage:profile> <xpackage:support support="required" level="restricted"/> <xmlprop:namespace rdf:resource="http://www.imsproject.org/xsd/ims_qti_rootv1p1"/> </xpackage:profile> </xpackage:processing> </xpackage:package>
The following properties are defined in the XPackage vocabulary represented by the namespace http://openebook.org/namespaces/package/2001/ and must only be associated with a package resource unless otherwise specified.
<xpackage:manifest>)A resource becomes a package resource by the presence of a manifest property. The purpose of the package resource manifest is to provide a definitive list of all resources that should be included in any package archive bundling for that package resource if it were to take place. Manifest resources are assumed to be so intrinsic to the package that their absence would cause normal processing of the package to fail. Inclusion in the manifest implies that a resource will always be available for processing in the context of the package description instance.
A package manifest is defined through use of a <manifest> element. This element must contain as a child an RDF <Bag> element, representing an RDF bag container. Each resource inside the RDF bag is bound to the package and must distributed with any package archive that uses that package description instance.
The package <manifest> element is described below using a non-normative XML schema fragment:
<xsd:element name="xpackage:manifest"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:Bag"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:li" maxOccurs="unbounded"> <xsd:complexType> <xsd:attribute name="rdf:resource" type="xsd:anyURI" minOccurs="1"/> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:sequence> </xsd:complexType> </xsd:element>
Each manifest resource in the RDF bag is referenced by the resource's unique identifying URI in the <rdf:li> element's rdf:resource attribute. This URI does not specify the location of the resource, but merely provides an identification of the resource. Each resource listed in the manifest should be defined elsewhere through use of an <rdf:Description> element (or one of RDF's equivalent abbreviated forms) with the same URI value in that element's rdf:about attribute. Some applications, however, may allow for resource definitions to be assumed by the context; those applications might not therefore require each resource to be defined in the package description.
The <manifest> element must include no elements other than the <rdf:Bag> element, which in turn must include no elements other than one or more <rdf:li> elements.
The following non-normative example illustrates the use of the <xpackage:manifest> element to define a package manifest in a package description:
<xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter1"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1png"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-stylesheet"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-rights"/> </rdf:Bag> </xpackage:manifest> </xpackage:package>
One might assume from the given URIs that the resources in the example manifest above are an XML document, a PNG image, a stylesheet, and rights metadata, respectively, but such an assumption cannot be made solely from the content of the resource URI. Moreover, such an assuption cannot be made solely from information provided in the package manifest. The package manifest only identifies resources — it does not describe them. Any description of resources in the package manifest must be provided elsewhere either in separate RDF statements or as part of a particular application context.
<xpackage:organization>)A package resource may have a default organization of a subset of the items included in the manifest. This organization is a linear ordering of some or all the items that compose the package resource, although future versions of this specification may allow hierarchical organizations. While an organization represents the default order of resources, it does not preclude other orderings or the capability for the user to experience variations of that ordering through, for example, interacting with an application's user interface.
The package organization is analogous to the spine of [OEBPS] version 1.0.1 and of the organization of [IMS Content Packaging] version 1.1.2. A package resource representing a book, for example, may have a default ordering of documents that compose the book's spine. A package resource representing a trilogy may have a default order of the books in the series, each of which is a book resource. A teacher's lesson plan may have a default ordering of books, interactive tutorials, assignments, and assessments.
The package organization is specified through use of an XPackage <organization> element, which must contain only an RDF <Seq> element. As each resource in the sequence makes up the default organization of the package, only resources declared in the package manifest may be included in the organization so as to ensure those items are included in any package archive, should any bundling take place.
The package <organization> element is described below using a non-normative XML schema fragment:
<xsd:element name="xpackage:organization"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:Seq"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:li" maxOccurs="unbounded"> <xsd:complexType> <xsd:attribute name="rdf:resource" type="xsd:anyURI" minOccurs="1"/> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:sequence> </xsd:complexType> </xsd:element>
As with the manifest, the organization does not define resources but merely references those resources and is restricted to resources also included in the manifest. As a non-normative example, the following XML fragment organizes a book into a linear sequence of documents (although such a package resource would likely be expressed as a specialized extension resource rather than by the general package resource element <package>):
<xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <--package manifest contents--> </xpackage:manifest> <xpackage:organization> <rdf:Seq> <rdf:li rdf:resource="urn:oeb:examplepackage1-preface"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter1"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter2"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter3"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-bibliography"/> </rdf:Seq> </xpackage:organization> </xpackage:package>
The documents in the previous example might represent a preface, three chapters, and a bibliography, although such information regarding the item resource contents cannot be derived from the literal resource URIs alone. Such content-related information may be included in the description of each corresponding item resource.
Many supporting items in the manifest (such as images and sound files of a book) may not be directly included in the organization but may instead be referenced from the contents of resources (such as XML documents) that are included in the organization.
<xpackage:fallback>)A package resource may declare substitution options for resources it contains. An XPackage processor may use a fallback description to determine an appropriate alternative for a resource. A fallback is included to serve use cases in which a resource is requested by some resource or application, and an application attempts to locate a substitution resource using the fallback rules described by a package resource. If an XHTML resource, for instance, embeds an animated GIF image that an application cannot handle, the application might refer to a fallback property that includes a PNG image as an alternative to the animated GIF.
Each fallback property defines a sequence of resources, each of which must also be contained in the package resource manifest. The order of a fallback sequence should indicate the preferred substitution order. If multiple fallback sequences include the requested resource, the XPackage processor should first attempt to choose a substitution resource from the fallback sequence in which the requested resource appears earliest in the sequence. The following informative algorithm expresses the substitution search order an XPackage processor should use for discovering fallback resources:
Nevertheless, an XPackage processor may choose a substitution resource from any fallback sequence that also contains the requested resource.
Fallback sequences are described using the XPackage <fallback> element, as described in the non-normative XML schema fragment below:
<xsd:element name="xpackage:fallback"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:Seq"> <xsd:complexType> <xsd:sequence> <xsd:element ref="rdf:li" maxOccurs="unbounded"> <xsd:complexType> <xsd:attribute name="rdf:resource" type="xsd:anyURI" minOccurs="1"/> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:sequence> </xsd:complexType> </xsd:element>
The example in which a package resource lists a PNG image as a suitable substitution for a GIF image is shown in the non-normative XPackage fragment below:
<xpackage:package rdf:about="urn:oeb:examplepackage1"> <xpackage:manifest> <--package manifest contents--> </xpackage:manifest> <xpackage:fallback> <rdf:Seq> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1gif"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1png"/> </rdf:Seq> </xpackage:organization> </xpackage:package>
The preferred substitution algorithm relies on order of appearance in the fallback sequence, which in the above example would usually indicate that the PNG resource is a substitution for a requested GIF resource. However, this specification does not mandate such sequencing, allowing an XPackage processor to use the above GIF resource as a substitution for a requested PNG resource, for example.
<xpackage:navigation>)[TBD: finish]
As specified elsewhere in this specification [TBD: link], any number of extension properties may be defined in separate vocabularies to describe properties needed by certain types of resources. One common type of resource is a resource encoded in XML. XML resources usually have a content type of text/xml, of application/xml, or ending in +xml. As XML resources are so prevalent (used even in the XPackage description document itself), this specification defines an extension property vocabulary specifically for those resources.
The following properties are defined in the XML property vocabulary represented by the namespace http://openebook.org/namespaces/package/xml-properties/2001/ and should only be associated with an XML resource unless otherwise specified.
<xmlprop:annotation>)An annotation is information, usually descriptive and user-defined, that should associated with a particular resource. An annotation is usually created at a later time than the creation of the resource it describes. Annotations are associated with a resource using the package <annotation> element.
The package <annotation> element allows an annotation resource to be referenced through use of the rdf:resource attribute, as illustrated in the following non-normative XML Schema fragment:
<xsd:element name="xmlprop:annotation"> <xsd:complexType> <xsd:attribute name="rdf:resource" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
The preferred form of annotations are those defined within a series of RDF statements. This allows the annotations to be directly included into the resource graph [TBD: define, or refer to RDFS] in a consistent way accessible to an RDF processor. This specification does not prescribe or provide a normative description of any annotation ontology. One ontology for describing annotations is the Annotea [Annotea] project of the W3C, which uses the http://www.w3.org/2000/10/annotation# namespace.
The following non-normative example assumes the Annotea namespace has been associated with the XML prefix annotea, and uses the Annotea ontology in the description of the annotation, creating an extension resource. Note that the example also uses the Dublin Core [DC], [DC RDF/XML] to provide metadata for the annotation, and assumes the Dublin Core namespace has been associated with the XML prefix dc (see "Metadata", below for more information on metadata):
<xpackage:description> <rdf:RDF> <xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1"> <xpackage:location xlink:href="chapter1.html"/> <xmlprop:annotation rdf:resource="urn:oeb:examplepackage1-chapter1-annotation"/> </xpackage:resource> <annotea:Annotation rdf:about="urn:oeb:examplepackage1-chapter1-annotation"> <rdf:type rdf:resource="http://www.w3.org/2000/10/annotationType#Comment"/> <dc:creator>Jane Doe</dc:creator> <dc:date>2001-10-04T22:16Z</dc:date> <annotea:context>#xpointer(id("heading2")/p[2])</annotea:context> <annotea:body>Notice how boring this chapter suddenly becomes.</annotea:body> </annotea:Annotation> </rdf:RDF> </xpackage:description>
The example associates the annotation identified by urn:oeb:examplepackage1-chapter1-annotation with the resource identified by urn:oeb:examplepackage1-chapter1. As this specification prescribes no specific annotation ontology, an XPackage processor may or may understand the semantics of the annotation item extension given above. An XPackage processor must correctly associate the extension the associating resource, and must identify the association as being of type http://openebook.org/namespaces/package/2001/annotation as specified by [RDF].
<namespace>)The namespace property indicates an XML namespace [XML Namespaces] used by a resource, and should therefore only be applied to resources that contain XML [XML]. A namespace is indicated by declaring its namespace URI in the XPackage <namespace> element, as shown by the following non-normative XML Schema fragment:
<xsd:element name="xmlprop:namespace"> <xsd:complexType> <xsd:attribute name="rdf:resource" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
A namespace as defined by [XML Namespaces] has a unique identifying URI. The rdf:resource attribute must identify the namespace by containing the namespace URI.
The following non-normative example illustrates expressing that a particular item resource contains XML elements from both the XHTML [XHTML] and MathML [MathML] namespaces:
<xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1"> <xpackage:contentType>text/html</xpackage:contentType> <xmlprop:namespace rdf:resource="http://www.w3.org/1999/xhtml"/> <xmlprop:namespace rdf:resource="http://www.w3.org/1998/Math/MathML"/> <xpackage:resource>
<xmlprop:script>)It may be useful for a resource to specify which Unicode code points [Unicode] it uses. In most cases, this information is provided to assist an application in determining groups of characters might be used to display the information in the resource. The XPackage <script> element specifies Unicode code points based upon Unicode script name as defined by [Script Names].
Informative: Each Unicode code point is assigned a single script name. Each script name indicates either a specific script such as Devanagari (used by several languages of India) or one of two special values:
A resource may indicate one or more scripts through use of the XPackage <script> element, as indicated by the non-normative XML Schema fragment below:
<xsd:element name="xmlprop:script" type="xsd:string"/>
A package description instance that indicates one or more scripts must only use values from the latest normative Unicode script names list, which is currently http://www.unicode.org/Public/UNIDATA/Scripts.txt for Unicode 3.1. An XPackage processor must interpret each script name value without regard to case. A processor may ignore unknown script name values and must continue processing the package description instance without error.
The following non-normative example declares that the given resource uses Unicode code points from both the Japanese Hiragana and Katakana scripts:
<xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter2"> <xpackage:location xlink:href="chapter2.html"/> <xmlprop:script>hiragana</xmlprop:script> <xmlprop:script>katakana</xmlprop:script> </xpackage:resource>
<style>)This specification allows a resources to be associated with another resources as style. Specifying that one resource is the style of another indicates that the resource provides information that governs the presentation of the other resource. Examples of style resources include stylesheets of CSS [CSS2] and XSL [XSL].
XPackage style information follows the semantics of [XML Style Sheets], although most of these properties as used by XPackage are intrinsic to the style resource itself (the RDF object), not of the style relationship. XPackage style follows both [XML Style Sheets] and HTML [HTML4], style sheets specified in a package description instance are considered to occur before any style sheets specified internally to the style resources, such as through the xml-stylesheet XML processing instruction or through the HTML link element.
The following normative table describes how XML style sheet properties [XML Style Sheets] are expressed in XPackage:
| XML Style Sheet Property | XPackage Expression |
|---|---|
| href | Style resource <xpackage:location> property. |
| type | Style resource <xpackage:contentType> property. |
| title | Style resource <rdfs:label> property. |
| media | Style resource <xpackage:media> property. |
| charset | [TBD: is this needed?] |
| alternate | [TBD] |
Declaring style information for a resource is done using the syntax illustrated by the following non-normative XML Schema fragment:
<xsd:element name="xmlprop:style"> <xsd:complexType> <xsd:attribute name="rdf:resource" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
In most of these cases, XPackage expresses these properties as aspects of the style resource itself, not of the style property. Such style-related properties should therefore be described in the description of that style resource. The following non-normative example illustrates assigning a CSS stylesheet to an XHTML document:
<xpackage:description> <rdf:RDF> <xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1"> <xpackage:location xlink:href="chapter1.html"/> <xpackage:contentType>text/html</xpackage:contentType> <xmlprop:style rdf:resource="urn:oeb:examplepackage1-stylesheet1"/> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-stylesheet1"> <rdfs:comment>A groovy stylesheet for use on the screen or on the printer.</rdfs:comment> <rdfs:label>Groovy Style Sheet</rdfs:label> <xpackage:location xlink:href="stylesheet1.css"/> <xpackage:contentType>text/css</xpackage:contentType> <xpackage:media>screen</xpackage:media> <xpackage:media>printer</xpackage:media> </xpackage:resource> </rdf:RDF> </xpackage:description>
[TBD: This form binds the title to the actual style resource. Do we want to somehow instead allow contextual titles? Similarly, a media indication that is bound to the relationship, not the resource?]
<xmlprop:unicode>)[TBD: should this be named <xpackage:codePoints>?]
The preferred method of indicating Unicode code points used by a resource is through the script property, which indicates the script name of a set of code points. There might be some instances, however, in which the identification of Unicode code points by script name is too broad. The XPackage Unicode property may specify Unicode code point ranges along as well as individual code points.
The XPackage <unicode> element allows Unicode code points to be identified using a regular expression as defined by [Unicode Regular Expressions]. The regular expression appears as content of the XML element, as illustrated in the following non-normative XML Schema fragment:
<xsd:element name="xmlprop:unicode" type="xsd:string"/>
The Unicode regular expression must only include single Unicode code points and locale-independent ranges according to [Unicode Regular Expressions]. The following non-normative fragment, for example, specifies that the resource urn:oeb:examplepackage1-chapter2 uses all the ASCII characters (0x0000-0x007F) except the lowercase letters 'a' through 'z', and also uses the superscript '2' (0x00B2):
<xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter2"> <xpackage:location xlink:href="chapter2.html"/> <--uses all ASCII characters (except the lowercase Latin letters) and a superscript '2'--> <xmlprop:unicode>[\u0000-\u007F-[a-z], \u00B2]</xmlprop:unicode> </xpackage:resource>
[TBD: should we leave off the outermost brackets?]
A package archive must contain at least one package description instance and at least the resources specified in the package description's manifest. The package archive may physically store its resources in a variety of configurations, including:
If one of the above configurations is used as a package archive using a package description document, the package description document file must be located in the root of the directory hierarchy. More than one package resource may be stored in a package archive, using one or more package description instances in one or more package description documents.
All examples in this section are non-normative.
The following example shows how to use XPackage as a simple packaging mechanism to group a single XHTML document with its related files. The related files include a CSS stylesheet, an image, and a single annotation. As the created package resource used for bundling has no strong identity or semantics as a separate entity, the general package resource <package> element is used.
<xpackage:description xmlns:xpackage="http://openebook.org/namespaces/package/2001/" xmlns:xmlprop="http://openebook.org/namespaces/package/xml-properties/2001/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:annotea="http://www.w3.org/2000/10/annotation-ns#"> <rdf:RDF> <xpackage:package rdf:about="urn:examples:xhtmldocument"> <xpackage:contentType>application/xpackage</xpackage:contentType> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:examples:xhtmldocument-doc"/> <rdf:li rdf:resource="urn:examples:xhtmldocument-stylesheet"/> <rdf:li rdf:resource="urn:examples:xhtmldocument-image"/> </rdf:Bag> </xpackage:manifest> <xpackage:organization> <rdf:Seq> <rdf:li rdf:resource="urn:oeb:xhtmldocument-doc"/> </rdf:Seq> </xpackage:organization> </xpackage:package> <xpackage:resource rdf:about="urn:examples:xhtmldocument-doc"> <rdfs:comment>The XHTML document.</rdfs:comment> <xpackage:location xlink:href="doc.html"/> <xpackage:contentType>text/html</xpackage:contentType> <xmlprop:namespace rdf:resource="http://www.w3.org/1999/xhtml"/> <xmlprop:stylesheet rdf:resource="urn:examples:xhtmldocument-stylesheet"/> <xmlprop:annotation rdf:resource="urn:examples:xhtmldocument-annotation"/> <dc:creator>Garret Wilson</dc:creator> </xpackage:resource> <xpackage:resource rdf:about="urn:examples:xhtmldocument-css"> <rdfs:comment>The document stylesheet.</rdfs:comment> <xpackage:location xlink:href="stylesheet.css"/> <xpackage:contentType>text/css</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:examples:xhtmldocument-image"> <rdfs:comment>A document image.</rdfs:comment> <xpackage:location xlink:href="image.png"/> <xpackage:contentType>image/png</xpackage:contentType> </xpackage:resource> <annotea:Annotation rdf:about="urn:examples:xhtmldocument-annotation"> <rdf:type rdf:resource="http://www.w3.org/2000/10/annotationType#Comment"/> <dc:creator>Jane Doe</dc:creator> <dc:date>2001-10-30T08:58Z</dc:date> <annotea:context>#xpointer(id("heading1")/p[3])</annotea:context> <annotea:body>I lost track of the subject here.</annotea:body> </annotea:Annotation> </rdf:RDF> </xpackage:description>
All resources other than the XHTML document are supportive and subordinate to the XHTML document. The organization appropriately lists the XHTML document as the sole document for display to the user.
This photo album example groups similar related files of the same importance, rather than a single file and its supporting resources as in the XHTML document example. The resulting package resource could be considered a photo album, but in this example that package resource still has no extended semantics other than a group of resources, and therefore continues to use the <package> element. (A special photo album with defined photo-album-specific semantics could create an extension resource [TBD: link] to define the photo album resource.)
<xpackage:description xmlns:xpackage="http://openebook.org/namespaces/package/2001/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:xlink="http://www.w3.org/1999/xlink"> <rdf:RDF> <xpackage:package rdf:about="urn:examples:photoalbum"> <xpackage:contentType>application/xpackage</xpackage:contentType> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:examples:photoalbum-image1"/> <rdf:li rdf:resource="urn:examples:photoalbum-image2"/> <rdf:li rdf:resource="urn:examples:photoalbum-image3"/> </rdf:Bag> </xpackage:manifest> <xpackage:organization> <rdf:Seq> <rdf:li rdf:resource="urn:examples:photoalbum-image1"/> <rdf:li rdf:resource="urn:examples:photoalbum-image2"/> <rdf:li rdf:resource="urn:examples:photoalbum-image3"/> </rdf:Seq> </xpackage:organization> </xpackage:package> <xpackage:resource rdf:about="urn:examples:photoalbum-image1"> <xpackage:location xlink:href="image1.png"/> <xpackage:contentType>image/png</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:examples:photoalbum-image2"> <xpackage:location xlink:href="image2.png"/> <xpackage:contentType>image/png</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:examples:photoalbum-image3"> <xpackage:location xlink:href="image3.png"/> <xpackage:contentType>image/png</xpackage:contentType> </xpackage:resource> </rdf:RDF> </xpackage:description>
This example illustrates a general resource, described using the XPackage <resource> element, that is also a package resource through its use of a manifest. It is not a general package resource, as it represents a physical file-based resource (the QTI assessment file) through the XPackage <location> property element. The resource media type is specified to be application/qti+xml, which would need to be defined by the QTI specification.
The package resource described is a Question/Test Interoperability (QTI) assessment [QTI]. The assessment references a single GIF image, ctpoint.gif. A PNG fallback is provided for the image, ctpoint.png.
This example is informative, and illustrates the use of QTI as defined in [QTI].
<xpackage:description xmlns:xpackage="http://openebook.org/namespaces/package/2001/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:xlink="http://www.w3.org/1999/xlink"> <rdf:RDF> <xpackage:resource rdf:about="urn:examples:qti"> <xpackage:contentType>application/qti+xml</xpackage:contentType> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:examples:qti-ctpoint-gif"/> <rdf:li rdf:resource="urn:examples:qti-ctpoint-png"/> </rdf:Bag> </xpackage:manifest> <xpackage:organization> <rdf:Seq> <rdf:li rdf:resource="urn:examples:qtia-assessment"/> </rdf:Seq> </xpackage:organization> <xpackage:fallback> <rdf:Seq> <rdf:li rdf:resource="urn:examples:qti-ctpoint-gif"/> <rdf:li rdf:resource="urn:examples:qti-ctpoint-png"/> </rdf:Seq> </xpackage:fallback> </xpackage:resource> <xpackage:resource rdf:about="urn:examples:qti-ctpoint-gif"> <xpackage:location xlink:href="ctpoint.gif"/> <xpackage:contentType>image/gif</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:examples:qti-ctpoint-png"> <xpackage:location xlink:href="ctpoint.png"/> <xpackage:contentType>image/gif</xpackage:contentType> </xpackage:resource> </rdf:RDF> </xpackage:description>
This example is informative, and illustrates the use of an Open eBook Publication version 2 as defined in [OEBPS2]. The OEBPS specification defines an extension resource element in the http://openebook.org/namespaces/publication-structure/2001/ namespace named <publication>.
<xpackage:description xmlns:package="http://openebook.org/namespaces/package/2001/" xmlns:xmlprop="http://openebook.org/namespaces/package/xml-properties/2001/" xmlns:oebps="http://openebook.org/namespaces/publication-structure/2001/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:annotea="http://www.w3.org/2000/10/annotation-ns#"> <rdf:RDF> <oebps:publication rdf:about="urn:oeb:examplepackage1"> <xpackage:contentType>application/oeb-publication</xpackage:contentType> <xpackage:manifest> <rdf:Bag> <rdf:li rdf:resource="urn:oeb:examplepackage1-navmain"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-bookrights"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-preface"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter1"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1gif"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1png"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-generalstylesheet"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-prefacestylesheet"/> </rdf:Bag> </xpackage:manifest> <xpackage:organization> <rdf:Seq> <rdf:li rdf:resource="urn:oeb:examplepackage1-preface"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-chapter1"/> </rdf:Seq> </xpackage:organization> <xpackage:fallback> <rdf:Seq> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1gif"/> <rdf:li rdf:resource="urn:oeb:examplepackage1-image1png"/> </rdf:Seq> </xpackage:fallback> <xpackage:metadata rdf:resource="urn:oeb:examplepackage1-bookrights"/> <xpackage:navigation rdf:resource="urn:oeb:examplepackage1-navmain"/> <xpackage:processing> <xpackage:profile> <xpackage:support support="optional"/> <xpackage:contentType>image/gif</xpackage:contentType> <xmlprop:namespace rdf:resource="http://www.w3.org/1999/xhtml"/> <xmlprop:namespace rdf:resource="http://www.imsproject.org/xsd/ims_qti_rootv1p1"/> </xpackage:profile> </xpackage:processing> <xpackage:processing> <xpackage:profile> <xpackage:support support="required"/> <xpackage:contentType>text/css</xpackage:contentType> </xpackage:profile> </xpackage:processing> <dc:title>XML Package Example</dc:title> <dc:type>example</dc:type> <dc:identifier rdf:resource="urn:oeb:examplepackage1"/> <dc:creator>Garret Wilson</dc:creator> <dc:subject> <rdf:Bag> <rdf:li>Specifications</rdf:li> <rdf:li>Examples</rdf:li> <rdf:li>eBooks</rdf:li> </rdf:Bag> </dc:subject> </oebps:publication> <xpackage:resource rdf:about="urn:oeb:examplepackage1-navmain"> <rdfs:comment>Main navigation file.</rdfs:comment> <xpackage:location xlink:href="navmain.ncf"/> <xpackage:contentType>text/xml</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-bookrights"> <rdfs:comment>File providing rights inormation for the book.</rdfs:comment> <xpackage:location xlink:href="bookrights.xml"/> <xpackage:contentType>text/xml</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-readrights"> <rdfs:comment>A fragment of the book rights file giving rights only for reading.</rdfs:comment> <xpackage:location xlink:href="bookrights.xml#read"/> <xpackage:contentType>text/xml</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-preface"> <rdfs:comment>The HTML document containing the preface.</rdfs:comment> <xpackage:location xlink:href="preface.html"/> <xpackage:contentType>text/html</xpackage:contentType> <xmlprop:namespace rdf:resource="http://www.w3.org/1999/xhtml"/> <xmlprop:stylesheet rdf:resource="urn:oeb:examplepackage1-generalstylesheet"/> <xmlprop:stylesheet rdf:resource="urn:oeb:examplepackage1-prefacestylesheet"/> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1"> <rdfs:comment>The HTML document containing the first chapter.</rdfs:comment> <xpackage:location xlink:href="chapter1.html"/> <xpackage:contentType>text/html</xpackage:contentType> <xpackage:metadata rdf:resource="urn:oeb:examplepackage1-readrights"/> <xmlprop:namespace rdf:resource="http://www.w3.org/1999/xhtml"/> <xmlprop:namespace rdf:resource="http://www.imsproject.org/xsd/ims_qti_rootv1p1"/> <xmlprop:stylesheet rdf:resource="urn:oeb:examplepackage1-generalstylesheet"/> <xmlprop:annotation rdf:resource="urn:oeb:examplepackage1-chapter1-annotation"/> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-chapter1-annotation"> <rdfs:comment>An annotation for the first chapter; it has no file location.</rdfs:comment> <rdf:type rdf:resource="http://www.w3.org/2000/10/annotationType#Comment"/> <dc:creator>Jane Doe</dc:creator> <dc:date>2001-10-04T22:16Z</dc:date> <annotea:context>#xpointer(id("heading2")/p[2])</annotea:context> <annotea:body>Notice how boring this chapter suddenly becomes.</annotea:body> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-generalstylesheet"> <rdfs:comment>A stylesheet to be used for most content.</rdfs:comment> <xpackage:location xlink:href="generalstylesheet.css"/> <xpackage:contentType>text/css</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-prefacestylesheet"> <rdfs:comment>A special stylesheet to be used only for the preface.</rdfs:comment> <xpackage:location xlink:href="prefacestylesheet.css"/> <xpackage:contentType>text/css</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-image1gif"> <rdfs:comment>An animaged image in GIF 89a format</rdfs:comment> <xpackage:location xlink:href="image1.gif"/> <xpackage:contentType>image/gif</xpackage:contentType> </xpackage:resource> <xpackage:resource rdf:about="urn:oeb:examplepackage1-image1png"> <rdfs:comment>A non-animated version of the GIF image, in PNG format.</rdfs:comment> <xpackage:location xlink:href="image1.png"/> <xpackage:contentType>image/png</xpackage:contentType> </xpackage:resource> </rdf:RDF> </xpackage:description>
This OEB publication lists the following files. The functions of the files shown in parentheses are not expressed in the manifest, but are instead expressed through properties:
package.xml (package)navMain.ncf (navigation)bookrights.xml (rights metadata)preface.xml, chapter1.html (documents)image1.gif, image1.png (images)generalStylesheet.css, prefaceStylesheet.css (stylesheets)While some metadata is expressed for the publication using Dublin Core properties, the publication's rights metadata is specified to be contained in the bookrights.xml file through use of the <xpackage:metadata> property. A fragment of the bookrights.xml file (bookrights.xml#read) is specified as a separate resource and is used as the rights for chapter1.html using the same mechanism.
Both preface.html and chapter1.html are associated with the stylesheet generalStylesheet.css, while preface.html is additionally associated with the stylesheet prefaceStylesheet.css.
This section is informative.
http://www.w3.org/2000/10/annotation-ns#http://purl.org/dc/elements/1.1/http://www.w3.org/1998/Math/MathMLhttp://www.w3.org/1999/02/22-rdf-syntax-ns#http://www.w3.org/2000/01/rdf-schema#http://www.w3.org/1999/xlinkhttp://openebook.org/namespaces/package/2001/http://openebook.org/namespaces/package/xml-properties/2001/http://www.w3.org/XML/1998/namespace[TBD: Define orders of priorities in, for example, stylesheet association and fallbacks.]
[TBD: A package as a shared databases of elements, used by other shared databases?]
[TBD: What about aliases so no content has to be modified for URIs?]
[TBD: Change [Script Names] to [Unicode Script Names].]