feat(catalog): derive metadata from repository state

[pedropaulofb]

Summary

This pull request improves synchronization of the OntoUML/UFO Catalog metadata by deriving catalog contributors from model metadata and by replacing manually maintained modification values with semantic change detection.

The catalog generator now determines whether the catalog collection itself changed, whether only catalog-level metadata changed, or whether no semantic change occurred. It then updates dct:modified and fdpo:metadataModified according to their distinct meanings.

The pull request also updates three catalog-level metadata values:

• replaces the direct GitHub repository URL used as storage_url with the OntoUML permanent identifier;
• replaces the earlier Barcelos-led conference-paper citation with the more recent Sales-led journal article;
• replaces the obsolete University of Bolzano contact email address with the current contact email address.

The previously implemented contributor aggregation behavior is retained.

Motivation

The previous catalog metadata required the following values to be maintained manually in catalog.yaml:

• modified;
• metadata_modified;
• the catalog contributor list.

This created several problems:

1. the modification values could become stale and no longer represent actual catalog changes;
2. setting timestamps during every generator execution would incorrectly treat no-op generation as a modification;
3. manually maintaining catalog contributors could cause the catalog-level contributor list to diverge from the contributors declared by the model datasets;
4. generated metadata could therefore cease to accurately represent the current repository state.

This implementation makes the generated catalog metadata dependent on the repository’s semantic content rather than manually synchronized values.

Changes

Derive catalog contributors from model metadata

The generator now derives catalog-level dct:contributor values from the union of all dct:contributor values declared in direct model metadata files:

models/*/metadata.ttl

The generated contributor set:

• includes contributors declared across all cataloged models;

• removes exact duplicate IRIs;

• identifies simple equivalent variants that differ only by:

  • http versus https;
  • a final trailing slash;

• deterministically retains one existing representative IRI for equivalent variants;

• does not attempt identity resolution between unrelated identifiers belonging to the same person;

• rejects contributor values that are not valid HTTP(S) IRIs.

The contributor list is no longer maintained manually in catalog.yaml.

Derive modification timestamps from semantic changes

The following fields were removed from catalog.yaml:

modified:
metadata_modified:

The generator now reads the existing catalog.ttl, generates the candidate catalog graph, and compares the RDF content semantically.

Timestamp predicates are excluded from the semantic comparison so that timestamps do not cause their own modification events.

The implemented behavior is:

Detected change	dct:modified	fdpo:metadataModified
No semantic change	Preserved	Preserved
Catalog metadata changed only	Preserved	Updated
Catalog membership changed	Updated	Updated
No existing catalog	Initialized	Initialized

Catalog membership is represented by the generated dcat:dataset relationships.

Catalog metadata includes the remaining generated catalog-level statements, such as:

• title;
• alternative title;
• description;
• storage identifier;
• citation;
• contact information;
• license;
• publisher;
• creators;
• contributors;
• language;
• keywords;
• other generated catalog metadata.

Preserve deterministic no-op generation

The generator compares RDF graphs rather than serialized Turtle text.

Consequently, the following do not update either modification value:

• triple reordering;
• prefix reordering;
• indentation changes;
• line-wrapping changes;
• equivalent Turtle serialization;
• running the generator again without a semantic source change.

A repeated no-op generation therefore remains byte-identical.

Use one UTC timestamp per semantic update

When a relevant semantic change is detected, the generator captures one UTC timestamp and reuses it for all properties that must be updated.

This ensures that catalog membership changes produce identical values for:

dct:modified
fdpo:metadataModified

New values are serialized as xsd:dateTime.

An existing legacy date-only dct:modified value is preserved until catalog membership changes, avoiding the invention of a historical time value that was never recorded.

Preserve safe --check behavior

--check evaluates whether the existing catalog is semantically synchronized without modifying files.

It does not generate a new current timestamp merely to perform validation.

The command exits successfully when the generated semantic content is current and reports whether detected staleness concerns:

• catalog metadata; or
• catalog membership.

Add controlled timestamp input

The generator supports an explicit generation timestamp for deterministic testing and controlled generation scenarios.

This allows the timestamp behavior to be tested without depending on the system clock.

Update catalog-level metadata

The catalog storage identifier is updated to:

http://w3id.org/ontouml/models

The bibliographic citation is updated to:

Prince Sales, T., Barcelos, P. P. F., Fonseca, C. M., Souza, I. V., Romanenko, E., Bernabé, C. H., Bonino da Silva Santos, L. O., Fumagalli, M., Kritz, J., Almeida, J. P. A., & Guizzardi, G. (2023). A FAIR catalog of ontology-driven conceptual models. Data & Knowledge Engineering, 147, 102210. https://doi.org/10.1016/j.datak.2023.102210.

The catalog contact email is updated to:

pedropaulofb@gmail.com

Update documentation and automated validation

The generator documentation now describes:

• contributor aggregation;
• contributor deduplication;
• semantic timestamp behavior;
• catalog-membership comparison;
• catalog-metadata comparison;
• first-generation behavior;
• legacy timestamp handling;
• no-op generation;
• --check;
• explicit generation timestamps.

The test suite includes regression coverage for the new behavior.

Validation performed

The following focused test suite was executed:

python -m pytest -q scripts/tests/test_generate_catalog_file.py

Result:

45 passed

The generated catalog was synchronized with:

python scripts/generate_catalog_file.py .

Synchronization was verified with:

python scripts/generate_catalog_file.py . --check

The generator was executed a second time and the generated catalog.ttl remained byte-identical, confirming deterministic no-op behavior.

Ruff validation was executed:

python -m ruff check \
  scripts/generate_catalog_file.py \
  scripts/tests/test_generate_catalog_file.py

Ruff formatting validation was executed:

python -m ruff format --check \
  scripts/generate_catalog_file.py \
  scripts/tests/test_generate_catalog_file.py

Python compilation validation was executed:

python -m py_compile \
  scripts/generate_catalog_file.py \
  scripts/tests/test_generate_catalog_file.py

The repository pre-commit configuration was also executed against the staged change set:

pre-commit run

All checks passed.

Scope

The pull request is limited to the catalog generation and release-validation files required for this implementation:

• .github/workflows/process-new-model-submission.yml
• .github/workflows/publish-models-release.yml
• catalog.yaml
• catalog.ttl
• scripts/generate-catalog-file.md
• scripts/generate_catalog_file.py
• scripts/tests/test_generate_catalog_file.py

No unrelated repository changes are included.