The Apache FOP Project

The Apache™ FOP Project

Apache™ FOP: Metadata

Overview

Document metadata is an important tool for categorizing and finding documents. Various formats support different kinds of metadata representation and to different levels. One of the more popular and flexible means of representing document or object metadata is XMP (eXtensible Metadata Platform, specified by Adobe). PDF 1.4 introduced the use of XMP. The XMP specification lists recommendation for embedding XMP metdata in other document and image formats. Given its flexibility it makes sense to make use this approach in the XSL-FO context. Unfortunately, unlike SVG which also refers to XMP, XSL-FO doesn't recommend a preferred way of specifying document and object metadata. Therefore, there's no portable way to represent metadata in XSL-FO documents. Each implementation does it differently.

Embedding XMP in an XSL-FO document

As noted above, there's no officially recommended way to embed metadata in XSL-FO. Apache™ FOP supports embedding XMP in XSL-FO. Currently, only support for document-level metadata is implemented. Object-level metadata will be implemented when there's interest.

Document-level metadata can be specified in the fo:declarations element. XMP specification recommends to use x:xmpmeta, rdf:RDF, and rdf:Description elements as shown in example below. Both x:xmpmeta and rdf:RDF elements are recognized as the top-level element introducing an XMP fragment (as per the XMP specification).

Example

[..]
</fo:layout-master-set>
<fo:declarations>
  <x:xmpmeta xmlns:x="adobe:ns:meta/">
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about=""
          xmlns:dc="http://purl.org/dc/elements/1.1/">
        <!-- Dublin Core properties go here -->
        <dc:title>Document title</dc:title>
        <dc:creator>Document author</dc:creator>
        <dc:description>Document subject</dc:description>
      </rdf:Description>
      <rdf:Description rdf:about=""
          xmlns:xmp="http://ns.adobe.com/xap/1.0/">
        <!-- XMP properties go here -->
        <xmp:CreatorTool>Tool used to make the PDF</xmp:CreatorTool>
      </rdf:Description>
    </rdf:RDF>
  </x:xmpmeta>
</fo:declarations>
<fo:page-sequence ...
[..]

fo:declarations must be declared after fo:layout-master-set and before the first page-sequence.

Implementation in Apache FOP

Currently, XMP support is only available for PDF output.

Originally, you could set some metadata information through FOP's FOUserAgent by using its set*() methods (like setTitle(String) or setAuthor(String). These values are directly used to set value in the PDF Info object. Since PDF 1.4, adding metadata as an XMP document to a PDF is possible. That means that there are now two mechanisms in PDF that hold metadata.

Apache FOP now synchronizes the Info and the Metadata object in PDF, i.e. when you set the title and the author through the FOUserAgent, the two values will end up in the (old) Info object and in the new Metadata object as XMP content. If instead of FOUserAgent, you embed XMP metadata in the XSL-FO document (as shown above), the XMP metadata will be used as-is in the PDF Metadata object and some values from the XMP metadata will be copied to the Info object to maintain backwards-compatibility for PDF readers that don't support XMP metadata.

The mapping between the Info and the Metadata object used by Apache FOP comes from the PDF/A-1 specification. For convenience, here's the mapping table:

Document information dictionary
Entry		 PDF type XMP Property XMP type XMP Category
Title text string dc:title Text External
Author text string dc:creator seq Text External
Subject text string dc:description["x-default"] Text External
Keywords text string pdf:Keywords Text External
Creator text string xmp:CreatorTool Text External
Producer text string pdf:Producer Text Internal
CreationDate date xmp:CreationDate Date Internal
ModDate date xmp:ModifyDate Date Internal

"Internal" in the Category column means that the user should not set this value. It is set by the application.

The "Subject" used to be mapped to dc:subject in the initial publication of PDF/A-1 (ISO 19005-1). In the Technical Corrigendum 1 this was changed to map to dc:description["x-default"].

Namespaces

Metadata is made of property sets where each property set uses a different namespace URI.

The following is a listing of namespaces that Apache FOP recognizes and acts upon, mostly to synchronize the XMP metadata with the PDF Info dictionary:

Set/Schema Namespace Prefix Namespace URI
Dublin Core dc http://purl.org/dc/elements/1.1/
XMP Basic xmp http://ns.adobe.com/xap/1.0/
Adobe PDF Schema pdf http://ns.adobe.com/pdf/1.3/

Please refer to the XMP Specification for information on other metadata namespaces.

Property sets (Namespaces) not listed here are simply passed through to the final document (if supported). That is useful if you want to specify a custom metadata schema.

PDF custom properties

It is possible to add custom key/value pairs in the Info dictionary of a PDF document. Those custom properties will appear in the ‘Custom’ tab of Adobe Reader’s ‘Document Properties’ window.

A pdf:info element can be added as a child of fo:declarations and contain the custom properties. For example:

<fo:declarations>
  <pdf:info xmlns:pdf="http://xmlgraphics.apache.org/fop/extensions/pdf">
    <pdf:name key="MyProperty">MyValue</pdf:name>
    <pdf:name key="MyOtherProperty">MyOtherValue</pdf:name>
  </pdf:info>
</fo:declarations>

PDF ViewerPreferences

You can set PDF viewer preferences for example using:

<fo:declarations>
  <pdf:catalog xmlns:pdf="http://xmlgraphics.apache.org/fop/extensions/pdf">
   <pdf:dictionary key="ViewerPreferences">
    <pdf:name key="Duplex">DuplexFlipShortEdge</pdf:name>
   </pdf:dictionary>
  </pdf:catalog>
</fo:declarations>

There is a specific element for each possible entry type: pdf:array, pdf:boolean, pdf:name, pdf:number, pdf:string. For example:

<fo:declarations>
  <pdf:layer id="Contents">
    <pdf:string key="Name">Contents</pdf:string>
  </pdf:layer>
  <pdf:layer id="Connections">
    <pdf:string key="Name">Connections</pdf:string>
  </pdf:layer>
  <pdf:catalog>
    <pdf:dictionary key="OCProperties">
      <pdf:array key="OCGs">
        <pdf:reference refid="Contents"/>
        <pdf:reference refid="Connections"/>
      </pdf:array>
      <pdf:dictionary key="D">
        <pdf:string key="Name">Default</pdf:string>
        <pdf:name key="BaseState">OFF</pdf:name>
      </pdf:dictionary>
    </pdf:dictionary>
  </pdf:catalog>
</fo:declarations>

Example 1 Example 2 Example 3

PDF Page Piece

Allows indexing of PDF files for tools such as IBM Content Manager OnDemand

Usage (fo)

Add metadata for each page master based on how the software has been configured.

<fo:simple-page-master master-name="simple" page-height="27.9cm" page-width="21.6cm">
  <fo:region-body />
   <pdf:pagepiece>
    <pdf:dictionary key="IBM-ODIndexes/Private">
        <pdf:string key="Cname">BUD</pdf:string>        
    </pdf:dictionary> 
  </pdf:pagepiece>        
</fo:simple-page-master>

PDF page metadata

Allows attaching custom XMP metadata to a specific PDF page object

Usage (fo)

<fo:simple-page-master master-name="simple">
  <fo:region-body/>
  <pdf:page page-numbers="*">
    <x:xmpmeta xmlns:x="adobe:ns:meta/">
      <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:abc="http://www.abc.de/abc/">
        <rdf:Description rdf:about="" abc:def="val"/>
        <rdf:Description rdf:about="" xmlns:pdfaExtension="http://www.aiim.org/pdfa/ns/extension/"
                         xmlns:pdfaSchema="http://www.aiim.org/pdfa/ns/schema#"
                         xmlns:pdfaProperty="http://www.aiim.org/pdfa/ns/property#">
          <pdfaExtension:schemas>
            <rdf:Bag>
              <rdf:li rdf:parseType="Resource">
                <pdfaSchema:property>
                  <rdf:Seq>
                    <rdf:li rdf:parseType="Resource">
                      <pdfaProperty:name>split</pdfaProperty:name>
                    </rdf:li>
                  </rdf:Seq>
                </pdfaSchema:property>
              </rdf:li>
            </rdf:Bag>
          </pdfaExtension:schemas>
        </rdf:Description>
      </rdf:RDF>
    </x:xmpmeta>
  </pdf:page>
</fo:simple-page-master>