Costasano Heritage Project — Asset Identifier & Numbering Specification (Draft v1)

Purpose

This document formalizes the agreed rules for the automatic identifier generation of Asset entities in the Costasano Heritage Project Drupal system.

The objective is to guarantee:

long-term stability of identifiers
simplicity for users
robustness across exports, URLs, and publications
compatibility with future systems

Identifiers must remain valid for decades and must never change once assigned.

---

Identifier Structure

The identifier of an Asset follows the format:

``` ChapterCode-ContextCode-Sequence ```

Example:

``` CH01ab-OOSTEN-01234 ```

Where:


| Component   | Meaning                     |
| ----------- | --------------------------- |
| ChapterCode | Historical timeline context |
| ContextCode | Place or Organisation       |
| Sequence    | Global asset counter        |

Maximum identifier length:

``` ≤ 19 characters ```

Structure calculation:

``` 6 + 1 + 6 + 1 + 5 = 19 ```

The identifier field in Drupal should allow at least **32 characters**.

---

Allowed Characters

Identifiers may only contain the following characters:

``` A–Z a–z 0–9 - ```

The dash `-` is used as separator.

Dots, spaces, and special characters are not permitted in identifiers.

This ensures compatibility with:

URLs
filenames
exports
MediaWiki references
scripts and APIs

---

Chapter Code Rules

Chapter codes are stable identifiers defining the historical timeline structure.

Format:

``` CHnn CHnna CHnnaa ```

Where:

| Part | Meaning                     |
| ---- | --------------------------- |
| CH   | fixed prefix                |
| nn   | two digits                  |
| a–z  | optional subdivision levels |

Examples:

``` CH01 CH01a CH01b CH01aa CH01ab CH02 ```

Rules:

maximum length: **6 characters**
only lowercase letters allowed for subdivisions
numbers are only used in positions 3–4
dots are not used

Example hierarchy:

``` CH01 main chapter CH01a subchapter CH01aa sub-subchapter ```

This structure preserves readability and avoids punctuation problems.

---

Context Code Rules

The context component represents either:

a Place
an Organisation

Only one context type may be used.

Example:

``` CH01ab-OOSTEN-01234 CH03-HYDRO1-00218 ```

Context codes:

maximum length: **6 characters**
normally uppercase
defined in their respective authority entities.

---

Sequence Number

The sequence number is a **global counter across all Assets**.

Example:

``` 00001 00002 00003 ```

Properties:

length: **5 digits**
range: `00001–99999`
globally incrementing
zero-padded for correct sorting

The sequence does not reset per chapter or per context.

The sequence field is stored in the Asset entity as:

``` field_as_sequence (integer) ```

---

Sequence Generation Rule

When a new Asset is created:

``` sequence = MAX(existing sequence) + 1 ```

Example:

``` existing max = 01432 new asset = 01433 ```

Sequence gaps are acceptable.

Example after deletion:

``` 01431 01432 01434 ```

Missing numbers are not reused.

---

Identifier Generation

The identifier is automatically generated on the first save of the Asset.

Steps:

1. Determine ChapterCode 2. Determine ContextCode (Place OR Organisation) 3. Compute next Sequence 4. Construct identifier

Example:

``` CH01ab-OOSTEN-01234 ```

The identifier is stored in:

``` field_as_code ```

---

Immutability Rules

Once an Asset is created, the following fields must never change:

``` Chapter Place Organisation Sequence Identifier ```

If the user made a mistake in these fields:

1. the incorrect asset must be deleted by the sysop 2. a new asset must be created.

Identifiers must never be edited manually.

---

Deletion Policy

Normal users are not allowed to delete Assets.

Permissions:

| Role         | Delete Assets |
| ------------ | ------------- |
| Contributors | No            |
| Enrichers    | No            |
| Sysop (mngr) | Yes           |

Deletion is restricted to system administrators.

Sequence gaps caused by deletion are acceptable.

---

Relationship With Files

Each Asset represents exactly one digital file.

Principle:

``` ONE asset = ONE file ```

File storage is managed by Drupal.

The identifier belongs to the Asset, not to the file itself.

Files are not renamed automatically.

Architecture:

``` Asset

└── Media
     └── File

```

This separation ensures long-term stability and flexibility.

---

Media Types (Planned)

Initial media types foreseen:

``` Image Document ```

Later optional type:

``` Video ```

Media types describe file handling and display, not archival classification.

Classification is handled by Asset metadata.

---

Validation Rules

Asset creation must enforce:

``` Place XOR Organisation ```

Meaning:

exactly one of the two must be selected
both cannot be filled simultaneously.

---

Design Principles

This numbering system follows the project design rules:

simplicity for elderly users
deterministic identifier generation
long-term archival stability
compatibility with external systems
minimal automation complexity

Identifiers must remain stable for decades.

Context Field Behaviour in Asset Forms

During the creation of an Asset, the user must select the contextual authority entities that define the identity of the asset.

The following fields are therefore editable only at creation time:

Chapter
Place OR Organisation

Exactly one of the two context authorities must be selected (Place XOR Organisation).

After the Asset has been saved for the first time, these fields become structurally immutable and cannot be modified by normal users.

---

Behaviour After Creation

When an existing Asset is opened for editing:

the fields Chapter, Place, and Organisation are displayed as read-only
the values remain visible to allow users to verify the context of the asset
the fields cannot be modified.

Example:

``` Chapter: CH01ab Place: OOSTEN ```

---

Navigation to Authority Entities

Although the fields are read-only, the displayed labels remain clickable.

Clicking the label opens the corresponding authority entity page (Place or Organisation) where users can inspect the detailed information.

Example interaction:

``` Place: OOSTEN → opens Place details page ```

The authority page allows users to view information such as:

name
type
address
geographical information
description and notes

This behaviour ensures that:

the identity of the Asset remains immutable
users can still navigate easily through the authority entities
contextual information remains transparent and accessible.

---

Rationale

This design supports the project principles:

preventing accidental structural changes to Assets
preserving identifier stability
allowing users to verify and explore contextual information without exposing technical database concepts.

---

Status

Specification agreed but not yet implemented.

Implementation will use:

Drupal entity presave event
automatic identifier generation
immutable fields after creation.

---