A complete reference of PageSeeder's markup language PSML

Migrating to PSML

This document is a guide on how to migrate existing documents from PS Standard XML format to PSML format.


An alternative to converting the existing PS Standard documents is to export them as Universal Format and upload them to a new PSML group. This may be more work than straight conversion and will not preserve the edit history or comments. However, it may be useful if the document or group structures are to be redesigned at the same time.


Any existing document versions on the PS standard may not produce the correct results. New fragments added after a version was created will still appear in that version of the document. Versions created after migrating to PSML should work correctly.


  1. Become familiar with PSML by reading the following:
    1. Universal format

    2. "PSML Quick Reference" and "PS Standard versus PSML" can be downloaded from Documents

    3. PSML element reference

    4. PSML Samples

    5. Document types

  2. Choose a project to convert to PSML. It will need to be done one project at a time.

  3. Convert the existing PS Standard configuration files by clicking Convert configuration to PSML on the Dev > Document config page for the project (in developer perspective). Note: This will not convert schematron, CSS or Ant publish script files.

  4. Create a test group under the project and ensure that all the document types can be created and edited:

    1. Creation via the New Document page should be tested for all document types.

    2. Existing PS standard documents in the project can also be exported as Universal Format and uploaded to the test group.

  5. Convert the existing Schematron, CSS and Ant publish scripts to work with PSML documents and check them in the test group. See the following documentation:

    1. PSML Schematron

    2. PSML document styles (CSS)

    3. <publishing>

    4. PSML Ant scripts

  6. If the PS project configuration is in a code repository like Mercurial or Git, then copy the converted configuration files to the repository. For example click Export in the Project Files page in PageSeeder and the Publish Engine, then unzip the files and copy them to Eclipse and Commit/Push to the repository.

Conversion Details

PS Label Values

Content inside <section ... format="pslabelvalues"/> will be converted to <properties-fragment>.

PS XRef List

Content inside <section ... format="psxreflist"/> or containing <xref type="replace|include" /> will be converted to <xref-fragment>.

Section tables

Content inside <section ...><title level="table"> will be converted to <media-fragment mediatype="text/plain">.


Converted Section tables to a single <section ... format="pslabelvalues"/> before conversion (by downloading, transforming, uploading).


For consistency, the PS standard conversion to PSML has been changed so that all values generated by the label values editor type=checkbox appear in the @value attribute and multiple values will be comma separated e.g.:

<property name="language" value="English"/>
<property name="language" value="English,Spanish"/>

Previously these would have been converted as:

<property name="language" value="English"/>
<property name="language">


Projects that use PSLabelValuesConfig with type=checkbox in EditorConfig.json may need to be modified to handle a @value attribute with comma separated content.

Alternatively, all content may be modified after conversion to PSML (by downloading, transforming, uploading or editing individually in dev perspective) to have multiple <value> and count="n" on the <property> element. The document-template.psml would also need to be updated.

Data type

After conversion, the @datatype attribute on <property> element will only be set if the property is not empty e.g.

<property name="related" value=""/>
<property name="related" datatype="xref" count="n"><xref ... /></property>

If the @datatype attribute is important in the project, all content may be modified after conversion to PSML (by downloading, transforming, uploading or editing individually in dev perspective) to have the correct @datatype and @count attributes. The document-template.psml would also need to be updated.



Before converting, ensure there is a recent PageSeeder database and filesystem backup.


After conversion, PS Standard XML documents will not be able to be uploaded or created in the group.

The following will need to be done for each group in the project.

  1. Go to the Group Manage page located under the Admin tab and click on Convert. Administrators can use the PSML migration page located under the Dev tab to convert whole projects at once.
  2. If the number of archived documents is large, they may be cleaned up by deleting some as they can take a long time to convert. To enable the delete function, add adminEnable=delete-documents in the
    1. Alternatively, the archive folder can be moved to another group and converted later. For this, a backup group under the project containing a folder with the name of the group could be used.
  3. Leave Validate Only ticked and click on Start
  4. If there are validation warnings/errors, click on Show Logs then click on the View next to each document with errors and fix it as described below. It can be useful to click 'Show Warnings and Errors only' or to view the logs in a larger window go to the Admin > Console or Admin > Group Console and view the Process logs.
    1. Warnings (in orange) can usually be ignored. Validation errors on the original PS Standard XML appear as warnings. If these can not be corrected by the conversion they will also appear as errors (in red), similar messages may appear twice.
    2. The warning Conversion will change XRef type to 'none' due to other content in body is because of a "replace/include" XRef in a <body> element that also has some other content. If the XRef is not required to be transcluded, for example, if only publishing to a website which doesn't require it, then this message can be ignored. Otherwise, the other content (including &nbsp;) can be removed or the XRef can be replaced with an XRef type "embed".
    3. The warning Invalid Doc ID "[x]" will be removed during conversion means that the Doc ID x is not valid and will be removed. If it is not to be removed then it needs to be changed to something valid via the Properties tab.
    4. If the document is no longer required it can be deleted.
    5. Fix validation errors by editing the document. It may be useful to look at the document XML by clicking <f> in the developer tools block and do a find for the start of the element (e.g. <list ).
    6. If there are no XRefs to the document fix validation errors by creating a new document, copy/pasting the old content, deleting the original and then renaming the new document.
    7. Fix validation errors by downloading the document, editing manually and uploading it again.
    8. The error Unable to backup PS standard document:... usually means that document is missing on the file system. To fix this either delete the document or find the missing file and copy it to the server file system.
    9. The error URI already exists for:... means that it is trying to convert a file [name].xml to [name].psml but [name].psml already exists. To fix this either archive, delete or rename [name].psml
    10. The error PSML different to PS Standard content at text character [n] the last character of "[content]" means that during the conversion the text at the end of [content] would be changed. This is may be because of non XRef content under a <section format="psxreflist">. If so it can be fixed by removing the non XRef content (including &nbsp;) or removing format="psxreflist".
    11. The error The value "[x]" of attribute @docid is wrong: expecting a "document-id" means there is an XRef or reverse XRef pointing to a document with an invalid Doc ID. This can usually be ignored as the conversion should remove the invalid Doc ID. If running the conversion a second time doesn't fix it , click on the XRef or reverse XRef to go to the document and then modify or delete the invalid Doc ID via the Properties tab.
    12. The error Exception parsing PS standard file usually means there is an encoding problem on the file. The document will need to be deleted or if there are no XRefs to the document, fix encoding errors by creating a new document, copy/pasting the old content, deleting the original and then renaming the new document.
    13. Some errors may say See document: followed by a file path. If there is a View link, the original PS standard document may be viewed in PageSeeder. However, to view the actual document file it must be accessed on the server file system under the pageseeder/documents/[group]/.backup folder. If using FTP , choose the option "show hidden files" to see them (e.g. In FileZilla select Server > Force Showing Hidden Files).
  5. Repeat steps 3 and 4 until there are no validation errors.
  6. Untick Validate Only and click on Start. This will do the final conversion of all the PS standard XML documents to PSML.

Created on , last edited on