The iWork XML Schemas

Extensible Markup Language (XML) is a ubiquitous and flexible markup standard for processing and exchanging data. You can find XML in a wide range of categories, including property lists and file formats for various applications. XML is used extensively to specify the format of various sources of information on the Internet, including web-based services. XML is at the heart of both iWork applications, Keynote and Pages, developed by Apple.

This chapter provides you with a high-level, architectural view of the document-based XML schemas used by both Keynote 2.x and Pages 1.x. As noted in the “Introduction,” Apple’s technical documents describing the Keynote XML schema pertain only to Keynote 1.x and are not relevant to any discussion of the current version of that application.

Developer Issues

Both Pages 1.x and Keynote 2.x, which form the basis of Apple’s iWork package, are powerful, yet easy to use applications that have attracted large and ever-growing customer bases. The iWork package is part of a family of iApps productivity tools.

Because Keynote uses an open, easily accessible file format, developers can take advantage of its XML schema to enhance existing products or create new ones. Beginning with Keynote 1.x, it is possible to build applications that will create or change the contents of a Keynote presentation. For example, developers can use any of Keynote’s themes and build an entire presentation of their own design simply by filling out the <key:slide-list> element in a text editor of their choice.

The Keynote APXL file is the engine that drives every presentation, specifying every detail of the presentation’s appearance and behavior––from master slide and each individual slide to the transitions used between slides. The APXL file also defines the state of the presentation when the user first opens it. An understanding of how the elements in an APXL file combine to create a presentation is critical to developing applications that are robust and well-behaved.

Similarly, understanding the Pages document structure is important for Apple developers who want to customize their own page layouts or add value to their existing applications.

Important Changes to the File Format

When Apple introduced Keynote 2.x, a number of new features were added to the application. In so doing, the document file format was significantly expanded and revised.

For developers of existing applications that read and write the Keynote 1.x file format, this has necessitated updating their code to read and write the new Keynote 2.x format.

What this means is that Keynote 2.x will read existing Keynote 1.x files, so developers can continue creating documents in the older file format programmatically from their applications. However, the original file will be converted to the new format and overwritten when it is saved from within Keynote 2.x.

Note that the file type name of Keynote was changed from presentation.apxl in Keynote 1.x to index.apxl in Keynote 2.x.

Defining the iWork XML Schemas

A schema determines the layout of an XML document’s elements, the attributes and subelements that each can have, and the constraints that the attribute data and element data must adhere to. XML schemas are used to define the structure, content and semantics of XML documents.

As with any XML file, Keynote and Pages XML consists of a series of elements, some of which may contain mixed content, while most include only attributes and/or child elements. Many elements have unique identifiers which allow them to be referenced by other elements.

Despite a number of internal differences, both iWork XML schemas represent an XML document as an ordered, labeled tree in which each node has a unique identity and may have a value, attributes, and namespaces associated with it.

The iWork XML schemas operate on the abstract, logical structure of an XML document—the data model—rather than its surface syntax. The data model represents an XML document as a tree of nodes. The tree can have various kinds of nodes, each of which corresponds to a type of XML construct, such as element, attribute, text, and namespace.

Each node in a tree typically has a unique identity. Most nodes have a name, and many have some string or other type of value associated with them.

To be usable in a particular context, an XML document must be well formed. This means that a document must have open and close tags for all its elements (in the correct sequence) and contain one root element. In addition, XML documents must have at least one XML declaration: an element that provides XML parsers with essential information needed to process a document and ensure that it is valid.

A valid document is one that follows the structure specified by a schema file, such as the Pages or Keynote schema files.

iWork XML Document Structures

This section discusses both the Keynote and Pages document structures, with a high-level architectural overview of the various elements and attributes that comprise each structure.

The Keynote Document Structure

If you deconstruct the XML for a valid Keynote presentation, you’ll find that it conforms to an ordered hierarchical list. A Keynote XML document follows the basic hierarchy shown in Listing 2-1, with the <key:presentation> element always at the top-level.

Listing 1-1  The Keynote XML hierarchy

<key:presentation>

    <key:theme-list>

        <key:theme>...</key:theme>

    </key:theme-list>

    <key:slide-list>

        <key:slides>...</key:slides>

    </key:slide-list>

    <key:ui-state>...</key:ui-state>

    <key:version-history>...</key:version-history>

    <key:size>...</key:size>

</key:presentation>

The Keynote XML format also specifies that the <key:theme-list> element must have at least one <key:theme> child element, and similarly, the <key:slide-list> element must have one or more <key:slide> child elements.

The hierarchy of the Keynote schema, with its ordering of elements and associated child elements, is illustrated in Figure 2-1.

Figure 1-1  The Keynote hierarchy of elements

Table 2-1 describes the usage of each Keynote child element.

Defining Characteristics

In Keynote, the top-level <key:presentation> element is comprised of a <key:theme-list> and a <key:slide-list>. A <key:theme-list>, in turn, is comprised of several themes, including one <key:stylesheet> and one or more master-slides, and in turn, each master-slide has a single <key:stylesheet>.

Within this structure, there are zero or more visible drawables: <key:body>, <key:title>, <key:slide-number>, and <key:object-placeholder>, each of which may or may not be in a list of visible drawables.

A <key:slide-list> element is comprised of one or more slides. A <key:slide> consists of one <key:stylesheet> and three layers, one of which is a master proxy layer. A layer is a container for drawables. A master proxy layer displays all of the visible drawables from the slide’s master-slide displayed in it. You can have one layer beneath or one layer over it, or just one layer over it. Every slide refers to one master-slide and each master-slide can have zero or more slides.

A <key:stylesheet> element for a slide inherits from the <key:stylesheet> for its master-slide. A <key:slide> element has three drawable layers.

A slide also has a <key:body>, <key:title>, <key:slide-number>, and <key:object-placeholder>, which, just like the master slide, may or not be visible. If they are visible, they will show these layers. And a slide has one or more <key:headlines>, the first of which is the <key:title>, and is always present. But it will not appear unless the title placeholder is present.

A slide has a single page, and a page has three layers, one of which is the master proxy layer, two of which are drawable layers. A master slide has one page which has a single drawable layer. Master slides have exactly six headlines, which have no text, and are empty. Headlines each have depths. The six headlines on master slide always have depths 0, 1, 2, 3, 4, and 5. In addition, both master slides and slides have a <key:thumbnail> element that contains a single image binary.

A presentation has a <key:size> element that specifies the slide size. Each theme also has a <key:size> element.

Style and Stylesheet Inheritance

Style and style sheet inheritance are important because if you break the inheritance, your document will behave in undefined ways.

In Keynote, there are three levels of stylesheet: theme (which has no inheritance), master, and slide. Master stylesheets always inherit from a theme stylesheet. Slide stylesheets always inherit from a master stylesheet. For reasons of performance, you have to explicitly set up these inheritance relationships.

A slide style cannot inherit directly from the theme style. It has to inherit from another element in its stylesheet or its parents’ master stylesheet.

A stylesheet’s parent is indicated by the <sf:parent-ref> child element, where the value of the sfa:IDREF attribute is the value of the sfa:ID attribute of the parent stylesheet’s <key:stylesheet> element.

The Pages Document Structure

The Pages document structure shares many substructures with the Keynote structure, with some notable exceptions, as discussed in this section. If you deconstruct the XML for a valid Pages document, you’ll find that it conforms to an ordered hierarchical list shown in Listing 2-2.

Listing 1-2  The Pages XML hierarchy

<sl:document>

    <sl:version-history>...</sl:version-history>

    <sl:publication-info>...</sl:publication-info>

    <sl:metadata>...</sl:metadata>

    <sl:print-info>...</sl:print-info>

    <sl:section-prototypes>

        <sl:prototype>

            <sl:stylesheet>...</sl:stylesheet>

            <sl:headers>...</sl: headers>

            <sl:footers>...</sl:footers>

            <sl:drawables>...</sl:drawables>

            <sl:text-storage>...</sl:text-storage>

            <sl:thumbnails>...</sl:thumbnails>

        </sl:prototype>

    <sl:/section-prototypes>

    <sl:stylesheet>...</sl:stylesheet>

    <sl:headers>...</sl: headers>

    <sl:footers>...</sl:footers>

    <sl:drawables>...</sl:drawables>

    <sl:text-storage>...</sl:text-storage>

    <sl:thumbnails>...</sl:thumbnails>

    <sl:window-configs>...</sl:window-configs>

</sl:document>

The Pages XML format specifies that the <sl:document> element is always at the top-level of a Pages document.

The <sl:prototype> elements define the captured pages and follow the structure of the document proper, which follows the <sl:section-prototypes> element, having child elements for stylesheet, headers, footers, drawables, text-storage, and thumbnails.

“Chapter 4, Working With Text Objects in Pages Documents,” describes in detail the usage of these elements and their attributes.

The hierarchy and structure of a Pages document is illustrated in Figure 2-2.

Figure 1-2  The Pages document hierarchy and structure with associated child elements

The children and their usage in a Pages document are described in Table 2-2:

Defining Characteristics

In a high-level view of the Pages document structure, the first notable difference between a Keynote document and a Pages document is the <sl:section-prototypes> element, which is unique to Pages. The <sl:section-prototypes> contains a list of <sl:prototype> elements that mimic the structure of the main pages document, less those parts which pertain to the document as a whole.

A Pages <sf:stylesheet> element has exactly the same format as a Keynote <key:stylesheet>, except in Pages there is only one stylesheet for the main document, and one for each captured page set.

The <sl:drawables> element contains all the floating objects either for the page set, or the main document. These are grouped in a manner similar to the way they are grouped in Keynote––that is, into a masters-group and page-groups. Both the page-groups and masters-group have essentially the same structure. The masters-group are for drawables that are on the section masters, while the page-groups are the other drawables, grouped by the page on which they appear.

The <sl:masters-group> has a <sl:section-drawables> element for each section in the document or page set, indicated by its <sf:style> child element. Each <sl:section-drawables> element also has child elements in its foreground and background groups, which are in the same format as the Keynote drawables.

The <sl:drawables> element has <sl:page-group> child elements for each page with floating drawables.

The main document and each page set also have <sl:headers> and <sl:footers> elements that contain the headers and footers stored as arrays of text storages, and <sl:thumbnails> elements that contain the page thumbnail images in an ordered list, similar to the way that thumbnails are stored in Keynote.

The<sl:window-configs> element is used to specify the window size, location, and scroll position, and where the selection was when the document was saved.

Stylesheet Inheritance

In Pages, as contrasted with Keynote, there is no stylesheet inheritance. There is just one stylesheet per capture page set, and one for the rest of the document.

Document Elements

The next section describes some of the document elements in a Pages document. It is intended as a symbolic representation of the Pages document format rather than strictly valid XML.

Version History

The version-history is purely informational and is not interpreted by the application.

Publication-Info

The publication-info is defined in the following XML.

<sl:publication-info>

    <sl:kSFWPFootnoteFormatProperty>

      <sl:number sfa:number="0" sfa:type="i"/>

    </sl:kSFWPFootnoteFormatProperty>

    .

     .

    <sl:SLCreationDateProperty>

      <sl:date sfa:ID="NSCalendarDate-0" sl:val="2005-04-19T20:39:39 +0000"/>

    </sl:SLCreationDateProperty>

    .

     .

    <sl:SLLastModifiedDateProperty>

      <sl:date sfa:ID="NSDate-0" sl:val="2005-04-19T22:16:41 +0000"/>

    </sl:SLLastModifiedDateProperty>

     .

     .

</sl:publication-info>

Metadata

The metadata element is defined in the following XML:

<sf:metadata>

    <sf:comment>...</sf:comment>

    <sf:copyright>...</sf:copyright>

    <sf:keywords>...</sf:keywords>

    <sf:authors>...</sf:authors>

    <sf:title>...</sf:title>

</sf:metadata>

Print-Info

Some of the print-info elements that appear in the Pages XML are as follows:

<sl:slprint-info sfa:ID="SLPrintInfo-0" sl:page-width="612" sl:page-height="792" sl:page-scale="1">

     <sf:page-margins sfa:ID="SFWPMargins-0" sf:top="72"  sf:left="72" sf:bottom="72"  sf:right="72" sf:header="36" sf:footer="43.200000762939453"/>

    <sl:print-info>

      <sl:NSJobDisposition>

      <sl:NSPaperSize>

      <sl:NSMustCollate>

      <sl:NSVerticalPagination>

      <sl:NSVerticallyCentered>

      <sl:NSPrintAllPages>

      <sl:NSCopies>

      <sl:NSBottomMargin>

      <sl:NSLeftMargin>

      <sl:NSTopMargin>

      <sl:NSLastPage>

      <sl:NSFirstPage>

      <sl:NSSavePath>

      <sl:NSOrientation>

    </sl:print-info>

</sl:slprint-info>

Section Prototypes

The section-prototypes XML describe the capture pages sets as follows:

<sl:section-prototypes>

    <sl:prototype sl:name="Text Page">

      <sf:stylesheet sfa:ID="SFSStylesheet-0">

        <sf:styles>

          <sf:paragraphstyle sfa:ID="SFWPParagraphStyle-0" sf:name="Free Form" sf:ident="paragraph-style-default">

                <sf:null/>

              </sf:listStyle>

              <sf:hidden/>

              <sf:underline/>

              <sf:underlineColor>

              <sf:word_strikethrough/>

              <sf:firstTopicNumber/>

            <sl:headers>...</sl: headers>

            <sl:footers>...</sl:footers>

            <sl:drawables>...</sl:drawables>

            <sl:text-storage>...</sl:text-storage>

            <sl:thumbnails>...</sl:thumbnails>

     </sl:prototype>

<sl:/section-prototypes>

Common Elements and Usage

Many elements in a Keynote or Pages document include a sfa:ID attribute, which assigns a unique name to the element by which it can be referred to elsewhere in the document, generally via a sfa:IDREF attribute.

A common use is when the same object appears in multiple places in the document, the first being the complete object with an sfa:ID attribute. In subsequent appearances, the object appears in an element of the same name and a -ref suffix with an sfa:IDREF attribute.

For example:

        <key:object sfa:ID="Object-0">…<key:object/>

        <key:object-ref sfa:IDREF="Object-0"/>

Both “Chapter 3, Deconstructing iWork Shapes and Drawable Objects,” and “Chapter 4, Working With Text Objects in Pages Documents,” discuss in detail the usage of these elements and attributes, with many XML examples for illustration.

Working With Document Bundles and Preferences

Both Pages documents and Keynote presentations are bundles. A bundle is a directory containing related resources and is treated as a single object (application, document, and so on) by Mac OS X. The term bundle refers both to the object and to the directory it represents.

Keynote and Pages document bundles contain a compressed XML file that describes the entire document, plus the media files that are used in the document, although certain media assets can be referenced externally.

For Keynote, some media files are actually kept in the theme bundles, which are part of the application. Likewise, media files belonging to Pages’ templates are referenced from the template bundles to help reduce the size of user documents. A user can also choose whether to copy QuickTime movies into the document bundle.

Package Contents

To view the contents of a Pages or Keynote file, you can control-click it, and select Show Package Contents from the contextual menu that appears.

A Keynote document bundle contains an index.apxl.gz file containing the compressed XML for the document, a Contents folder that contains only the bundle PkgInfo, and a Thumbs folder, which stores a thumbnail image of each slides (seen in the slide sorter on the left column of the application). Media assets are also saved here.

Likewise, a Pages document bundle contains an index.xml.gz file containing the compressed XML for the document, a Contents folder that contains only the bundle PkgInfo, and a Thumbs folder, which stores thumbnail images of the pages. Media assets are also saved here.

The XML files use standard zlib compression, and may be decompressed by double-clicking the file, or with the gzip command-line tool. The applications can also recognize the files in their uncompressed form (without the .gz extension). Be aware that the compressed version is preferred if both exist in the document bundle.

Note that a Keynote 2.x index file is called index.apxl, while a Pages 1.x index file is specified simply as index.xml.

Decompressed Keynote Files

If you decompress a Keynote document’s index.apxl.gz file and open it in a text editor, you’ll see something similar to what is shown in Listing 2-3.

Listing 1-3  Decompressed Keynote XML viewed in a text editor

 <key:presentation xmlns:sfa="http://developer.apple.com/namespaces/sfa"  xmlns:sf="http://developer.apple.com/namespaces/sf" xmlns:xsi="http://www.w3.org/ 2001/XMLSchema-instance" xmlns:key="http://developer.apple.com/namespaces/ keynote2" sfa:ID="BGShow-0" key:play-mode="interactive"  key:kiosk-slide-delay="5"  key:kiosk-build-delay="2" key:mode="once" key:version="2004102100"> 

    <key:theme-list sfa:ID="NSMutableArray-0">

    <key:theme sfa:ID="BGTheme-0" key:name="Theme" key:decimal-tab=".">

      <key:size sfa:w="800" sfa:h="600"/>

      <key:stylesheet sfa:ID="SFSStylesheet-0">

        <sf:styles>

.

.

.

.

    <key:slide-list>

        <key:slide sfa:ID="BGSlide-6" key:depth="0">

    <key:ui-state>

    <key:version-history>

    <key:size>

</key:presentation>

In every Keynote document, the <key:presentation> element has a number of attributes, including four namespaces that are used throughout the document: (sfa, sf, xsi, and key), and a key:play-mode.

The <key:presentation> elements’ children include <key:theme-list>, <key:slide-list> , <key:ui-state>, <key:version-history>, and <key:size>, as discussed earlier in this chapter.

In the example shown in Listing 2-4, you’ll see the partial structure of elements from the beginning of a <key:theme-list> element to the beginning of a child <sf:styles> element.

Listing 1-4  Keynote XML order from theme-list to styles

  <key:theme-list sfa:ID="NSMutableArray-0">

    <key:theme sfa:ID="BGTheme-0" key:name="Theme" key:decimal-tab=".">

      <key:size sfa:w="800" sfa:h="600"/>

      <key:stylesheet sfa:ID="SFSStylesheet-0">

        <sf:styles>

            .

            .

            .

Here the <key:theme-list> element has three children: a <key:theme> with a key:name attribute, a <key:size> with attributes specifying the width a sfa:w and the height sfa:h, and a <key:stylesheet>.

Decompressed Pages Documents

If you decompress a Pages document’s index.xml.gz file and open it in a text editor, you’ll see something similar to what is shown in Listing 2-5 near the bottom of the file.

Listing 1-5  Decompressed Pages XML

<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8">

  <sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/>

  <sf:attachments/>

  <sf:footnotes>...</sf:footnotes>

  <sf:text-body>

    <sf:section sf:name="Chapter 1" sf:style="section-style-0">

      <sf:layout sf:style="layout-style-20">

        <sf:p sf:style="paragraph-style-32">Main body text.<sf:br/></sf:p>

        <sf:p sf:style="SFWPParagraphStyle-44">Second paragraph with a

<sf:span sf:style="SFWPCharacterStyle-5">character</sf:span> style and a<sf:tab/>tab.<sf:br/></sf:p>

        <sf:p sf:style="paragraph-style-32">

          <sf:br/>

        </sf:p>

        .

        .

        .

      </sf:layout>

    </sf:section>

  </sf:text-body>

</sf:text-storage>

In this example, the <sf:text-storage> element has an attribute, sf:kind, which specifies that it pertains to the text in the document’s main body.

The <sf:text-storage> element has four children: a <sf:stylesheet-ref>, which is a reference to a style sheet that appears earlier in the document, the <sf:attachment> and <sf:footnotes> elements, and a <sf:text-body> element.

The <sf:text-body> element has one or more child elements: an <sf:section>, which itself has one or more child <sf:layout> elements, which in turn has one or more <sf:p> elements, each of which has a sf:style attribute that specifies the identifiers of the sections, layouts, and paragraphs, respectively, of the first section, layout, and paragraph of the main body text.

Setting Preferences

Both Pages and Keynote have several preferences you can set that make it easier to work with their XML files:

defaults write com.apple.iWork.Pages SaveCompressionLevel 0

defaults write com.apple.iWork.Keynote SaveCompressionLevel 0

When the SaveCompressionLevel default is set to 0, the XML file will not be compressed. The normal value is 3.

defaults write com.apple.iWork.Pages FormatXML YES

defaults write com.apple.iWork.Keynote FormatXML YES

When the FormatXML default is set to YES, the XML will be written formatted for easier viewing and editing. The normal value is NO.