---
title: "PageSeeder objects"
source: https://dev.pageseeder.com/guide/document_modeling/pageseeder_objects.html
description: "PageSeeder objects are specialized primitives categorized as URIs (documents, folders, files), Locators (document fragments), XLinks (comments, tasks, versions, workflows), and Groups (projects). The flexible primitives-to-objects architecture has remained stable for 20 years while supporting evolving web environments."
last_updated: 2026-08-11T16:38:11+10:00
tokens: ~2707
---

# PageSeeder objects

PageSeeder [primitives](/guide/document_modeling/pageseeder_primitives.md) 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](http://www.w3.org/TR/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](/reference/glossary/uri.md) are specialized by their **type** (that is, media type), which represents objects such as:

- [PSML – PageSeeder Markup Language](/reference/glossary/psml.md) documents – which have a type of `application/vnd.pagaseeder.psml+xml`:
- [Folder](/reference/glossary/folder.md) – type is `folder`.
- Or objects of other types, such as:


  - images – when type is `image/*`.
  - videos – when type is `video/*`.
  - documents – when type is [PDF documents](/reference/glossary/pdf_documents.md), [DOCX files](/reference/glossary/word_docx_format.md), etc.
- [URL](/reference/glossary/url.md) external to the [PageSeeder server](/reference/glossary/pageseeder_server.md).

![uri\_objects.png](/content/images/modeling/uri_objects.webp)

### Documents and folders

#### PSML documents

These are documents created using the [PSML](/psml/elements.md) 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](/reference/glossary/metadata.md) fields. For an example of this capability, *see *[How to use metadata to substitute lo-res with hi-res images](/get_started/tutorials/substitute_lo-res_with_hi-res_images.md).

#### Folders

For common applications, the folder object provides hierarchical or typed grouping for documents or files. It is further specialized when used to [share](/reference/glossary/sharing_document.md) documents.

## Locator objects

Locator objects are specialized by **context**:

- Group Locator: 


  - Default
- Document Locators: 


  - Default
  - Fragments
- Sections are containers for fragments.

![locator\_objects.png](/content/images/modeling/locator_objects.webp)

### Locators and fragments

All documents have a default locator.

```text

#default
```

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](/reference/glossary/labels.md).

### 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.

> **Note:** 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.

![fragments\_example\_1.png](/content/images/modeling/fragments_example_1.webp)

### 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`.

> **Warning:** 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.

![fragments\_example\_2.png](/content/images/modeling/fragments_example_2.webp)

## XLink objects

[XLinks](/reference/glossary/xlink.md) are specialized by both their **role** and their **status**.

The most common types of XLinks are:

- [Comments](/reference/glossary/comment.md)
- Edits
- Notes
- [Version](/reference/glossary/version.md)
- [Workflow](/reference/glossary/workflow.md)
- [XRefs](/reference/glossary/cross_reference.md)

Other types used for:

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

![xlink\_objects.png](/content/images/modeling/xlink_objects.webp)

### 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](/reference/glossary/task.md) by setting a status to a comment. Discussions are linear and ordered chronologically.

The title generally remains unchanged.

![comments.png](/content/images/modeling/comments.webp)

### Tasks

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.

![tasks.png](/content/images/modeling/tasks.webp)

### 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.

![edits.png](/content/images/modeling/edits.webp)

### Edit notes

[Edit notes](/reference/glossary/edit_note.md) are attached to specific document edits. They are used for document review and audit.

### Versions

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

Each document [version](/reference/glossary/version.md) retains the state of document so that the document version can be exported or published.

### Workflows

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

There can only be one Workflow per [document](/reference/glossary/document.md) 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

[Xrefs](/reference/glossary/xref.md) (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**.

![groups.png](/content/images/modeling/groups.webp)

### Projects

A [Project](/reference/glossary/project.md) is a logical container for groups and an important configuration point. It defines the following:

- Labels
- Templates
- Configuration
- Project properties
- [Document types](/reference/glossary/document_type.md)

#### Subprojects

Projects can also be organized into a hierarchy using [subprojects](/reference/glossary/sub_project.md). This is usually done when groups need to be organized in a more complex structure for semantic reasons.

### Groups

A [Group](/reference/glossary/group.md) is used as working space.

It inherits the following from its parent project:

- Labels
- Template
- Configuration

But it can also define its own:

- [Properties](/reference/glossary/group_properties.md)
- Documents, tasks and comments.

#### Subgroups

A group can have one or more [subgroups](/reference/glossary/subgroup.md), but they are NOT hierarchical. Any group can be made a subgroup of another group (called the [supergroup](/reference/glossary/supergroup.md)) 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](http://demo.pageseeder.com/ps/page/subgroups-glossary/member/list?username=sjones&password=pageseederdemo).

## *Next...*

With primitives and objects in mind, let’s see how to turn a set of [Requirements](/guide/document_modeling/requirements.md) into a PageSeeder model.