View source for ICT:Numbering v 4.0

= 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:

  {{#cargo_query:
   tables=DigitalAssets
   |fields=MAX(sequence_number)=maxnum
   |where=chapter_id={{{chapter_id}}} AND context_code='{{{context_code}}}'
  }}

Then:

  {{#expr: {{{maxnum|0}}} + 1 }}



== Step 4 – compose identifier ==

  {{chapter_code}}-{{context_code}}-{{padleft:counter|4|0}}

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.