HERITRACE

HERITRACE is a web-based semantic data editor. It allows users 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.

mkdir heritrace && cd heritrace && \
curl -o docker-compose.yml https://raw.githubusercontent.com/opencitations/heritrace/main/docker-compose.yml && \
docker compose up

The compose file includes two Virtuoso databases and the web application. Once the databases pass their health checks, the application starts at http://localhost:5000.

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

With your own databases

Edit docker-compose.yml: remove the dataset-db, provenance-db, and networks blocks, remove depends_on and networks from the web service, then set DATASET_DB_URL and PROVENANCE_DB_URL to your database endpoints.

docker compose up

Stopping

docker compose down

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.