Skip to main content

PageSeeder objects

PageSeeder primitives are specialized into objects by attributes (@type or @role), or context (group, document, etc.). The primitives are very stable:

  • The implementation has barely changed in 20 years.
  • The original design was based on W3C XLink and earlier standards.

This isn’t the case for the PageSeeder objects. As the computing environment, particularly the Web, has evolved, so have the objects. It is the flexibility of the primitives-to-objects specialization that validates the link-based architecture.

PageSeeder implementations, that have been in continual use since the year 2000, support this argument. Groups with thousands of documents and comments are currently running on the latest PageSeeder version without ever needing the original data to be restructured. 

URI objects

URIs are specialized by their type (that is, media type), which represents objects such as:


Documents and folders

PSML documents

These are documents created using the PSML format. Because this format is native to PageSeeder, PSML documents can be edited, versioned, validated, linked to, annotated and more.

Some of this functionality is available to other formats but no other document type has the complete support of PSML.

Binary files

For files such as images and PDF documents, PageSeeder can support custom metadata fields. For an example of this capability, see How to use metadata to substitute lo-res with hi-res images.


For common applications, the folder object provides hierarchical or typed grouping for documents or files. It is further specialized when used to share documents.

Locator objects

Locator objects are specialized by context:

  • Group Locator:
    • Default
  • Document Locators:
    • Default
    • Fragments
  • Sections are containers for fragments.


Locators and fragments

All documents have a default locator.


Folders do not have a default locator.

In practice, fragments are immutable.

Fragment is synonymous with Locator in the context of document editing and for linking.

Sections and fragments

In PSML documents:

  • Sections are predefined containers for fragments set in the original document or the document template.
  • Section fragments are related to a section.
  • Section fragments generally inherit properties of the section and are positioned in relation to the section.

Other type of documents only have document fragments. There is no concept of sections for non-PSML document.

All document fragments have semantics, such as Labels.

Sections and fragments: example 1

In the following example, Document is a video and the fragments are created for each particular point in time inside the video.

Any time resolution could be used – PageSeeder only requires a unique identifier. It would also be possible to use more precise times, ranges or include coordinates in the video frame at that instant.


Sections and fragments: example 2

In this example, the document used is in PSML format.

Sections are fragment containers. They correspond directly to the sections found in the physical form of the document, that is, the XML file in the file system. PageSeeder refers to this file to determine the existence and ordering of the sections because sections do not have a natural ordering.

In this case, section #title appears before #metadata and #content.

The original file determines the sections in a document, but they could possibly be replaced when the document is uploaded. If the section IDs in the uploaded document do not match, existing data for the removed sections might be lost. Any related fragment is hidden from view but remains stored in the database.

Section fragments are locators conceptually attached to a section. The order of fragments related to a section is stored in the PageSeeder database and might not be their numerical order.


XLink objects

XLinks are specialized by both their role and their status.

The most common types of XLinks are:

Other types used for:

  • Archived XLinks.
  • Attachments & uploads.
  • Deleted content.


Comments and discussion

Comments can be attached through a Locator to the following:

  • A group (on the general discussion URI).
  • A document.
  • A document fragment.

Comments can also be attached to another comment. A sequence of comments is a discussion. A discussion can be changed into a task by setting a status to a comment. Discussions are linear and ordered chronologically.

The title generally remains unchanged.



A task is a discussion where at least one comment has a status.

A task update is a comment which has a status, assignment, priority or due date in a task.

Tasks can be attached to documents or be general, like any discussion. In fact, a discussion is turned into a task by specifying a status.

Each subsequent comment can change the task status, priority or reassign.

  • The role of the member affects who can do what.


Document edits

Document edits only apply to Locators within a PageSeeder PSML document. All edits have content.

A sequence of edits is the edit history. This can be used to track changes.

The content of new edits replaces previous ones. The content of a fragment is that of the last edit in the sequence.

History of changes is preserved by the edit sequence. Changes can be computed by comparing individual edits.


Edit notes

Edit notes are attached to specific document edits. They are used for document review and audit.


Document versions are attached to a document through its default Locator.

Each document version retains the state of document so that the document version can be exported or published.


A workflow is a special type of task that uses document status values (such as Initiated, In Progress, Complete, Approved, Terminated).

There can only be one Workflow per document and the status of the document is the workflow status.

It can have a current priority, due date and assigned to like other tasks and can use labels.

Workflows can be created on multiple documents at the same time but they are independent from each other.


Xrefs (cross-references) link two document fragments.

They are directed and they can be bidirectional so that each end of the link knows of each other.

They are persistent. Because links operate between Locators, they remain even if the documents move or are archived.

Other XLink types

  • Archived XLinks:
    • When XLinks are no longer needed or relevant, they are archived instead of being deleted.
  • File XLinks are created every time a document is:
    • Uploaded
    • Created
    • Attached
  • When a fragment is removed, a special XLink type is used to hide it from view.

Group objects

Groups are specialized by their flags and their name.



A Project is a logical container for groups and an important configuration point. It defines the following:


Projects can also be organized into a hierarchy using subprojects. This is usually done when groups need to be organized in a more complex structure for semantic reasons.


A Group is used as working space.

It inherits the following from its parent project:

  • Labels
  • Template
  • Configuration

But it can also define its own:


A group can have one or more subgroups, but they are NOT hierarchical. Any group can be made a subgroup of another group (called the supergroup) and they are not organized in a hierarchy.

The only effect is that members of a subgroup appear as members of the supergroup and have permission/notification settings as if they were direct members.

For example if there are 3 groups:

  • glossary
  • book1
  • book2

and glossary has subgroups with the following settings:

  • book1: Notification = Inherit, Role = Reviewer
  • book2: Notification = Inherit, Role = Reviewer

This means that the members of book1 have access to glossary as Reviewers and with notification the same as in book1. The same is true for members of book2.

This example is taken from an online demo which can be accessed here .


With primitives and objects in mind, let’s see how to turn a set of Requirements into a PageSeeder model.

Created on , last edited on