Identifier and Numbering Strategy

This page defines the official strategy for generating stable, human-readable identifiers and page names for entities created in the Costasano Heritage Database.

The goal is to ensure:

consistency
uniqueness
predictability
easy sorting
long-term stability
minimal editorial effort

Identifiers must be generated automatically wherever possible.

Manual numbering is not permitted.

Purpose

Identifiers serve three functions:

provide stable page names
support chronological and contextual grouping
enable simple referencing in research, citations, and exports

Identifiers are technical labels, not semantic descriptions.

They must never encode complex meaning or editorial interpretation.

Core principle

Identifiers are:

mechanical
uniform in structure
automatically generated
independent of entity semantics

Entity meaning is modeled in fields and relationships — not in the identifier itself.

The data model must never be distorted to simplify identifiers.

Scope

This numbering strategy applies to:

DigitalAsset pages
HeritageObject pages (if numbered)
other research entities where sequential registration is required
file names derived from DigitalAssets

It does NOT apply to:

Persons
Keywords
lookup tables

Identifier structure

Standard format

All numbered entities use the same structure:

 CHAPTER–CONTEXT–COUNTER

Example:

 CH03-ROM-0007
 CH02-ARCH-0012
 CH01-SAN-0003

Components

Chapter

Short code of the ResearchChapter.

Provides narrative grouping.

Examples:

CH01
CH02
CH03

Context

Short code describing where or by whom the entity is primarily associated.

The context may reference either:

an Organization (actor), or
a Place (location)

Only ONE context is used.

Examples:

ROM (Rome – Place)
FLO (Florence – Place)
ARCH (Archive – Organization)
CONG (Congregation – Organization)

The context slot is intentionally neutral.

It does not distinguish whether the source is an Organization or a Place.

Counter

A sequential integer:

unique within (Chapter + Context)
zero padded
automatically generated

Examples:

 0001
 0002
 0003

Padding ensures correct lexical sorting.

Full example

 CH03-ROM-0015

Means:

Chapter 03
Context Rome
15th registered entity in this group

Nothing more.

Relationship to the data model

Conceptual rule

Identifiers must NOT determine entity semantics.

Specifically:

cities are Places (not Organizations)
organizations remain actors
identifiers simply reference a context code

If both a Place and an Organization exist, the editor chooses the most appropriate contextual grouping for numbering.

This is an editorial convenience only.

Why context is unified

The system deliberately uses one neutral "context" slot instead of:

 chapter–organisation–counter
 chapter–city–counter

because conditional formats:

complicate generation
break sorting
create inconsistent identifiers
increase maintenance

Uniform structure is mandatory.

Required fields

Organizations

Organizations must include:

name
short code (unique)
place (optional)

Places

Places must include:

name
short code (unique)
optional hierarchy

Chapters

ResearchChapters must include:

title
short code

Short codes should:

be short (3–6 characters)
be stable
avoid spaces
avoid punctuation
not be changed after use

Automatic generation (Page Forms + Cargo)

Overview

Identifiers are generated automatically during form submission.

Process:

1. editor selects Chapter 2. editor selects either Organization or Place 3. system determines context code 4. system calculates next counter using Cargo query 5. system builds page name 6. page is saved using that name

Step 1 – store codes

Each of:

ResearchChapters
Organizations
Places

must contain:

 code (string)

Example:

 CH03
 ROM
 ARCH

Step 2 – determine context code

Pseudo logic:

 if organization exists → use organization.code
 else → use place.code

Only one is required.

Step 3 – compute next counter

Cargo query:

Error: Table DigitalAssets not found.

Then:

Step 4 – compose identifier

 Template:chapter code-Template:context code-counter

Use this value for:

page name
id field
display label

Step 5 – file naming

Uploaded files should reuse the same identifier:

 CH03-ROM-0015.jpg
 CH03-ROM-0015.tif

Benefits:

easy matching
export safety
external archival compatibility

Editorial workflow

Creating a new DigitalAsset

Editor:

uploads file
opens DigitalAsset form
selects chapter
selects place or organization
saves

System:

assigns number automatically
creates page with generated name

Rules for editors

Editors must NOT:

type identifiers manually
reuse old numbers
change page titles after creation
encode meaning in identifiers

Design principles

The numbering system prioritizes:

stability over meaning
simplicity over flexibility
automation over manual control

Identifiers exist only to identify.

All interpretation belongs in structured metadata.

Status

This document defines the official identifier strategy.

All new implementations and forms must follow this specification.