HERITRACE

HERITRACE (Heritage Enhanced Repository Interface for Tracing, Research, Archival Curation, and Engagement) is a semantic editor designed for professionals in galleries, libraries, archives, and museums (GLAM).

This system facilitates non-technical domain experts in enriching and editing metadata in a semantically robust manner. It is developed with a focus on user-friendliness, provenance management, change tracking, customization, and integration with heterogeneous data sources.

📚 Documentation

Complete documentation is available at: https://opencitations.github.io/heritrace/

🚀 Quick start

Prerequisites: Docker and Docker Compose

Download HERITRACE configuration:

curl -o docker-compose.yml https://raw.githubusercontent.com/opencitations/heritrace/main/docker-compose.yml

Optionally download database management scripts for quick setup:

For Unix/Linux/macOS:

curl -o start-databases.sh https://raw.githubusercontent.com/opencitations/heritrace/main/start-databases.sh

curl -o stop-databases.sh https://raw.githubusercontent.com/opencitations/heritrace/main/stop-databases.sh

chmod +x start-databases.sh stop-databases.sh

For Windows:

curl -o Start-Databases.ps1 https://raw.githubusercontent.com/opencitations/heritrace/main/Start-Databases.ps1

curl -o Stop-Databases.ps1 https://raw.githubusercontent.com/opencitations/heritrace/main/Stop-Databases.ps1

Demo Mode: HERITRACE runs in demo mode by default (FLASK_ENV=demo) for immediate testing without authentication setup.

Optional Configuration: Edit docker-compose.yml to customize:

• Database endpoints: Update DATASET_DB_URL and PROVENANCE_DB_URL if using your own databases

Launch Options:

Option A: Quick start with provided databases

Start databases first:

./start-databases.sh

or on Windows:

.\Start-Databases.ps1

Start HERITRACE:

docker compose up

Option B: Use your existing databases

Edit docker-compose.yml with your database URLs, then start HERITRACE:

docker compose up

The application will be available at http://127.0.0.1:5000

Stopping the application:

Stop HERITRACE:

docker compose down

Stop databases (if using provided scripts):

./stop-databases.sh

or on Windows:

.\Stop-Databases.ps1

For production setup with ORCID authentication and advanced configuration, see: Application Settings

🎯 Customization

HERITRACE is data model agnostic: use SHACL to define forms and validation constraints for your domain, and YAML display rules to customize the visual presentation.

• Application Settings
• SHACL Schema Configuration
• Display Rules Configuration

🔧 Development

For development setup and testing:

• Testing Guide
• CI/CD Pipeline

📖 Key features

HERITRACE bridges the gap between sophisticated semantic technologies and the practical needs of cultural heritage professionals:

• Provenance management and change tracking: Complete change history and versioning with detailed tracking of who, when, and what changed
• Time machine and Time vault: Timeline interface for version management and recovery of past versions of the data
• Intelligent metadata management: Real-time SHACL validation, disambiguation, and dynamic field configuration
• ORCID integration: Secure authentication allowing only authorized personnel to make modifications
• Seamless RDF integration: Works out-of-the-box with existing RDF datasets and any triplestore

For a detailed overview of features and technical foundation, see our User Guide for details on how to get started.

📄 Paper

Massari, A., & Peroni, S. (2025). HERITRACE: A User-Friendly Semantic Data Editor with Change Tracking and Provenance Management for Cultural Heritage Institutions. Umanistica Digitale, 9(20), 317–340. https://doi.org/10.6092/issn.2532-8816/21218

Arcangelo Massari is a PhD candidate in Cultural Heritage in the digital ecosystem at the University of Bologna.

🙏 Acknowledgments

This work has been partially funded by Project PE 0000020 CHANGES - CUP B53C22003780006, NRP Mission 4 Component 2 Investment 1.3, Funded by the European Union - NextGenerationEU.

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.

🔗 Links

• Documentation
• OpenCitations