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, first step in implementation operational - see appendid below.

Implementation uses:

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

Changed during implementation: Replace Sequence field by Counter field for readability

---

Appendix: Automatic Asset Identifier Generation

Purpose

Each Asset receives a unique, stable identifier automatically generated by the system when the Asset is created. This identifier is the permanent reference used across the Costasano Heritage Project.

Identifiers must remain stable over time and must never be modified once assigned.

---

Identifier Structure

The identifier follows the structure:

``` ChapterCode-ContextCode-Sequence ```

Example:

``` CH00-OOSTEN-00001 CH01a-HYDRO1-00002 ```

Components:

| Component   | Meaning                     |
| ----------- | --------------------------- |
| ChapterCode | Historical timeline segment |
| ContextCode | Place OR Organisation       |
| Sequence    | Global asset counter        |

The identifier is stored in the Drupal Title field of the Asset entity.

---

Sequence Counter

The sequence is a global counter stored in the field:

``` field_as_counter ```

Properties:

integer value
automatically incremented
formatted as a five-digit number
padded with leading zeros

Example:

``` 00001 00002 00003 ```

Sequence generation rule:

``` next counter = MAX(existing counter) + 1 ```

Sequence gaps are acceptable if records are deleted by the system administrator.

---

Context Determination

The context part of the identifier is derived from one of two authority entities:

Place
Organisation

Exactly one must be selected when creating the Asset.

Examples:

``` CH01ab-OOSTEN-01234 CH02-HYDRO1-01235 ```

The context code is taken from the label of the referenced authority entity.

---

Generation Workflow

When a new Asset is saved:

1. The system reads the highest existing counter. 2. The counter is incremented. 3. The sequence number is formatted to five digits. 4. The identifier is assembled:

``` ChapterCode-ContextCode-Sequence ```

5. The identifier is written to the Title field.

This process occurs automatically during the Drupal entity presave event.

---

Structural Field Immutability

After the Asset is created, the following fields become immutable:

``` Chapter Place Organisation ```

These fields are removed from the edit form to prevent accidental modification.

If a mistake was made during creation:

the incorrect Asset must be deleted by the system administrator
a new Asset must be created.

---

Design Rationale

This approach ensures:

deterministic identifier generation
minimal cognitive load for users
long-term stability of references
compatibility with URLs, exports, and external publications.

Identifiers therefore function as permanent archival references within the system.