Skip to main content

 Universal format

Portable, metadata and processed PSML

Universal Portable Format

For PageSeeder data, the Universal Portable Format is the metaphorical equivalent of a USB drive. It can be unplugged from one server and plugged into another.

Publications that might be composed of a tens of thousands of linked documents and images can be packaged into a single zip file and can be subsequently uploaded to a new server with complete fidelity. The features are:

  • A consistent, standalone representation of a PS file set.
  • Isomorphic conversion to/from PageSeeder (history and comments excepted, these are part of the group, not the document):
    • Includes all the necessary files plus a manifest.
    • Links fully resolved with relative paths.
  • Packaged in the widely supported ‘zip’ format.
  • Standard PageSeeder interfaces for processing portable format include:
    • Upload input/Export output.
    • Start and Endpoint for numerous Apache Ant tasks.


The universal format package which can be a single zip file consists of the following folders/files:

  • META-INF folder contains manifest.xml and a PSML metadata file [relative path].psml for every folder and non-PSML file in the package (e.g. META-INF/images/figure1.jpg.psml).

Any META-INF files are optional when uploading the package to PageSeeder.

  • META-INF/_urls folder contains a PSML metadata file [scheme]/[host]/[port]/[Unique ID].psml for every URL (external URI) referenced in the package (e.g. META-INF/_urls/http/

The Unique ID can be any string unique for that scheme/host/port. For an XRef to reference a URL the @href attribute must match the URL. When uploading the URL metadata files can be directly under META-INF/_urls (e.g. META-INF/_urls/1234.psml).

  • All files in the exported set are relative to a specified context. For example /ps/acme/specs/documents/spec.psml with context /ps/acme/specs would be documents/spec.psml).
    • Where export set files in _local folder are outside the specified context, relative to the context group. For example, a file such as /ps/acme/specs/images/figure1.jpg with context of /ps/acme/specs/documents would be represented as images/figure1.jpg. Without a context group /acme, it would go in _external.
    • The export set files in _external folder are outside the specified context and the source group. For example, /ps/acme/products/images/figure2.jpg with source and context /ps/acme/specs/documents would be /acme-products/images/figure2.jpg.

The manifest.xml lists all the documents in the export set in the following format:

  <uri id="123"
    scheme="http" host="" port="80"
    decodedpath="/ps/acme/specs/documents/my spec.psml"
    documenttype="spec" />

Non-PSML documents are expressed as the <document> element and attribute level="metadata". Only the <documentinfo> element is required with <fragmentinfo> optional. 

<document level="metadata">
    <uri id="234"
         host="" port="80"
         decodedpath="/ps/acme/products/images/figure 2.jpg"
      <displaytitle>Figure 2</displaytitle> 
      <description>Overall system diagram</description> 

All PageSeeder PSML files have level="portable" on the <document> element. <documentinfo>, <fragmentinfo> and <reversexrefs> elements are all included.



GroupPath (in group)References
acme-specsdocuments/book.psmlgraph.jpg, figure1.JPG, figure2.jpg




{OUT}/book.psml (References: graph.jpg, _Local/images/figure1.JPG,
Created on , last edited on