HERITRACE

HERITRACE is a Web-based semantic editor for galleries, libraries, archives, and museums (GLAM). It allows domain experts without technical background to edit and enrich RDF metadata, while keeping track of every change with full provenance.

The full documentation is at opencitations.github.io/heritrace.

Quick start

You need Docker and Docker Compose.

Download the compose file:

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

Optionally, download the database management scripts:

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

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

By default HERITRACE starts in demo mode (FLASK_ENV=demo), so you can try it without setting up ORCID authentication.

With the provided databases

./start-databases.sh   # .\Start-Databases.ps1 on Windows
docker compose up

With your own databases

Edit docker-compose.yml to set DATASET_DB_URL and PROVENANCE_DB_URL, then:

docker compose up

The application will be available at http://localhost:5000.

Stopping

docker compose down
./stop-databases.sh    # if you used the provided databases

For production setup with ORCID authentication, see Application settings.

Features

• Provenance and change tracking -- every edit records who changed what and when, with full version history
• Time machine -- browse and restore previous versions of any entity
• SHACL validation -- forms and constraints are generated from SHACL shapes, with real-time validation and disambiguation
• ORCID authentication -- restricts editing to authorized users
• Works with any RDF dataset -- connects to any SPARQL-compatible triplestore, no data migration needed

See the user guide for more details.

Customization

HERITRACE is data model agnostic. You define your domain through SHACL shapes (for forms and validation) and YAML display rules (for presentation):

• Application settings
• SHACL schema
• Display rules

Development

• Testing guide
• CI/CD pipeline

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

Acknowledgments

HERITRACE was developed as part of the PhD thesis of Arcangelo Massari, a joint doctorate between the University of Bologna (PhD in Cultural Heritage in the Digital Ecosystem, Cycle 38) and KU Leuven (Arenberg Doctoral School, Faculty of Engineering Technology), supervised by Silvio Peroni and Anastasia Dimou.

License

ISC. See the LICENSE file.