Skip to main content

PageSeeder primitives

This article introduces some of PageSeeder’s key primitives:

Understanding these primitives helps to explain the properties of higher level objects that are exposed through the API or the user interface.

This is not an exhaustive list of primitives or their attributes—it is an introduction to those which are typically most significant.

Identifiers for primitives

Most primitives can be referenced by either a system identifier or a public identifier.

System IdentifiersPublic Identifiers
Assigned by PageSeeder – for a single server onlyAssigned by a user – can integrate externally managed IDs. For example, part numbers or ISBN codes
Immutable – does not change over timeOften mutable – can be changed
Unique – system-wide, within their classUnique – within different sets
Examples – URI ID, Member ID, XLink ID, Group IDExamples – DocID, Group name


A URI is an addressable entity: it has a specific and unique URL.

URIs can have Locators, which are anchor points to which XLinks can be attached.

A URI can be shared between groups and it can resolve or map to the following:

  • A file or directory in the file system.
  • OR another addressable resource.
  • OR nothing!

Every document in PageSeeder is a URI, including the following:

  • PSML documents.
  • Non-native documents (PDF, Images, Videos, Office documents, text files, arbitrary XML).
  • Folders.

URLs (aka External URIs) point to external resources.

Special URI in group to attach general XLinks.

Labels can be used to attach semantics.


  • id – a system and immutable identifier.
  • docid – a public identifier for the host but is mutable.
  • scheme, host, port, path – making the full URL unique.
  • title and description – similar to the role these play for Microsoft Word documents or PDF files. 
  • mediatype – the media type, for example, application/vnd.pageseeder.psml+xml 
  • GroupURIs (aka group folders) are used to share a URI.


XLinks are PageSeeder’s fundamental unit. They associate content created by a Member to Locators or to another XLink.

An XLink can have custom semantics (through labels) and has built-in workflow attributes (status, due date and more). They can also be moderated and PageSeeder keeps track of moderation and modifications.

An XLink can be assigned to a Member or shared between Groups through shared URIs.

In PageSeeder, XLinks are used to represent the following:

  • Comments.
  • Task changes.
  • Document Versions.
  • Document Edits.
  • Cross references.
  • Links between documents.
  • … more.

XLink sequences

Attached to the same Locator or XLink, a sequence of XLinks can be used to represent:

  • A threaded discussion.
  • The changing states of a task.
  • The editing history of a document fragment.
  • A document workflow.

By acting like a time machine on a Locator, sequences of XLinks provide the information that’s essential for formal audit trails. 


  • ID
  • Role & Title.
  • Content*
  • Creation author & date.
  • Modification member & date.
  • Assign member & date.
  • Priority, status and due date.
  • Properties and labels.
  • Other XLinks in sequence.
  • The ID is a system and immutable identifier.
  • The author is generally a Member but not necessarily.
  • Properties and labels are used to provide semantics.
  • Priority, status, assigned member and due date are used for workflows.


A locator is an anchor point and is used to attach XLinks. It is addressable as {uri(scheme, host, port, path)}#{fragment}. For example,

A URI can have multiple locators:

  • Each locator is unique within the URI.

There are special locators in PageSeeder:

  • For the document itself.
  • To refer to the group (for properties).

The document default locator is used for:

  • Comments and tasks on the document.
  • Document version.

The document fragment locators are used for:

  • Comments on document fragments.
  • Document editing.

The group default locator is used for:

  • Group properties.


  • ID
  • Fragment
  • The Locator ID is an immutable system identifier.
  • The fragment is unique within a URI.


A Member represents either a person who has an account on PageSeeder or another type of actor such as an external system. A Member is used to define credentials.

XLinks in PageSeeder are generally authored by a member.


  • ID
  • Email
  • Username
  • Other/given name and family name.
  • Password
  • Notification preferences.
  • The Member ID is an immutable system identifier.
  • Both the email and username can be used as public identifiers but they are mutable.


A Group is the social unit in PageSeeder and is essentially a collection of Members with specific Membership properties.

Groups are configurable—the behavior and functionality is customizable at the group level.

Groups can be public or private.

There are special types of groups:

  • Personal groups.
  • Projects and sub-projects.


  • ID
  • Name
  • Description & related URL.
  • Visibility, owner and flags.
  • Template
  • Membership fields.
  • The Group ID is an immutable system identifier.
  • The name is a public identifier.


A membership expresses the relationship between a Group and a Member.

It is used to define:

  • The role of the member in the group.
  • The notifications settings of the member for the group.
  • Group specific fields.


  • ID
  • Role
  • Notification & Email settings.
  • Moderator details.
  • The ID is an immutable system identifier.


See how PageSeeder primitive are specialized into PageSeeder objects.

Created on , last edited on