PID-LAND Palette — Representation Example

🚧 WORK IN PROGRESS — NOT PRODUCTION

This repository contains a PID-LAND Palette developed for the PID-LAND Representation Engine (RE).

It is part of the ongoing PID-LAND architectural refactoring.

The current production implementation remains in the main branch of PID-LAND.

This repository is provided as a working implementation and as a reference for the architecture presented in the FDO-LAND workshop.

---

This repository contains a PID-LAND Palette built around the PID-LAND Representation Engine.

While the Representation Engine provides the generic execution engine, a Palette defines how Digital Objects can be represented by supplying Hues, domain-specific modules and configuration.

The Representation Engine executes. The Palette defines the representations.

Prism separates representation mechanics from domain knowledge.

The engine knows how to produce a representation.

The Palette knows which representations are available.

This repository should therefore be considered both:

• a working example of a PID-LAND Palette;
• a starting point for developing new representation collections;
• part of the ongoing PID-LAND architectural refactoring.

---

Relationship with the Representation Engine

PID-LAND intentionally separates the representation engine from the application domain.

The Representation Engine is responsible for:

• request dispatching;
• representation selection;
• Hue loading;
• configuration management;
• logging;
• workflow orchestration.

The Palette provides:

• Hues;
• domain-specific modules;
• schemas;
• project-specific configuration.

This separation allows the same Representation Engine to support multiple independent domains without modifying the engine itself.

---

Repository Structure

palette/
│
├── hues/          # Representation implementations
├── modules/       # Domain-specific reusable components
├── schema/        # JSON Schema and SHACL validation
├── config/        # Palette configuration
├── utils/         # Palette utility functions
└── README.md

Each directory represents one aspect of the representation logic executed by the Representation Engine.

---

Core Components

A Palette is composed of three main elements.

Hues

Hues are the fundamental representation units of a Palette.

Each Hue is responsible for producing exactly one representation of a Digital Object.

Typical examples include:

• WF-Handle
• WF-Provenance
• Latest miniSEED
• Version miniSEED
• WF-Search
• WF-Select
• Citation
• RO-Crate

Each Hue follows the same workflow:

Parse request
        │
Validate request
        │
Retrieve domain information
        │
Build representation
        │
Send representation

A Hue orchestrates the workflow but delegates domain-specific operations to reusable modules.

---

Modules

Modules provide reusable domain capabilities.

Typical responsibilities include:

• metadata access;
• provenance retrieval;
• archive loading;
• waveform slicing;
• format conversion;
• validation;
• RO-Crate generation.

Modules perform the work.

They should not define workflows.

Whenever possible, complexity should be implemented inside Modules rather than inside Hues.

---

Schemas

Schemas define the structural rules for Digital Object representations.

They are used to validate:

• incoming requests;
• metadata;
• generated representations;
• RO-Crates;
• domain objects.

Validation logic remains independent from representation logic.

---

Developing New Hues

One of the design goals of PID-LAND is that Hues can be developed independently from the Representation Engine.

Developers should not need to modify Prism while implementing a new representation.

For this reason, every Hue follows the same execution contract.

---

Hue Contract

Every Hue follows the same workflow.

Parse request
        │
Validate request
        │
Retrieve domain information
        │
Build representation
        │
Send representation

This common structure makes Hues predictable and easy to understand while allowing each representation to remain completely independent.

---

Recommended Development Workflow

The recommended workflow for implementing a new Hue is intentionally simple.

Copy an existing Hue
          │
          ▼
Implement the representation
          │
          ▼
Execute the Hue
          │
          ▼
Validate the representation
          │
          ▼
Move reusable logic into Modules
          │
          ▼
Register the Hue inside Prism

Developing Hues independently from the Representation Engine considerably simplifies testing and debugging.

Only after a Hue has been validated should it be exposed through the Representation Engine.

---

Design Philosophy

Palettes are expected to follow the same philosophy as the Representation Engine.

Keep Palettes:

• simple;
• modular;
• readable;
• reusable.

Whenever possible:

• add a new Hue instead of modifying an existing one;
• move reusable capabilities into Modules;
• keep infrastructure independent from representations.

Following the Bicycle Principle, complexity should emerge from the Palette—not from the Representation Engine itself.

---

Representation Philosophy

PID-LAND no longer considers a PID as a reference to a resource.

Instead, a PID identifies persistent information.

Representations are generated on demand.

A single Digital Object may expose many different representations.

PID
 │
 ▼
Persistent Information
 │
 ├── WF-Handle
 ├── WF-Provenance
 ├── Latest miniSEED
 ├── Version miniSEED
 ├── WF-Search
 ├── WF-Select
 ├── Citation
 ├── RO-Crate
 └── Future representations...

The Representation Engine selects the appropriate Hue to materialize the requested representation.

---

Final Principle

Technology changes.

Information continues the journey.