Configuration editor
HERITRACE has two kinds of configuration that administrators edit in the app:
- System settings: the title, the provenance defaults, the deletion rules and who may sign in.
- Resource types: the data model, written as SHACL shapes as described in SHACL configuration.
Open the account menu and choose Configuration, or go to the /settings page. Only the ORCID iDs listed in ADMIN_ORCIDS see this menu entry.
Where the configuration lives
Section titled “Where the configuration lives”The configuration lives in the folder set by CONFIG_DIR. The folder holds these files:
| File | Content |
|---|---|
shacl.ttl | The resource types, as SHACL shapes in Turtle. It is optional |
shacl-editor.ttl | The resource types in the form the editor works on, in Turtle |
shacl-provenance.trig | The history of the resource types, as provenance snapshots in TriG |
settings.db | The system settings, in an SQLite database |
HERITRACE reads the folder when it starts. Without shacl.ttl, it starts with no resource types and creates the file, so you can add resource types later in the Resource types tab. On the first start, HERITRACE checks shacl.ttl and records its content as the first version of the resource types, leaving the file as it is.
The editor needs a name for each part of the shapes, while SHACL leaves many of them as blank nodes. HERITRACE therefore keeps a copy of the shapes in shacl-editor.ttl, where every blank node has an IRI; the history in shacl-provenance.trig refers to these IRIs. HERITRACE keeps the two files in sync. A change made in the app updates the copy and the history, then rewrites shacl.ttl from it, turning those IRIs back into blank nodes; the rewrite drops the comments and layout of a hand-written file. The copy is also what allows editing shacl.ttl by hand: comparing the file with it tells HERITRACE what changed. HERITRACE then reloads, rebuilds the copy and records the new content as a version of the resource types, in which the parts written as blank nodes start a new history.
Setup mode
Section titled “Setup mode”HERITRACE needs valid system settings to run, and valid resource types when shacl.ttl exists. When settings.db is missing, when its settings have an error, or when shacl.ttl cannot be used, HERITRACE starts in setup mode:
- Only administrators can sign in. After signing in, they land on the System tab.
- The tab shows administrators the error that blocked the start.
- Every other API request answers with status 503 until an administrator saves valid settings.
On the first start, the System tab shows the default values: complete them and save. When the error is in shacl.ttl, fix the file and restart HERITRACE.
Editing at the same time
Section titled “Editing at the same time”Only one administrator at a time can edit the system settings. While someone edits them, the others see who is editing when they choose Edit. Resource types and fields work like the resources of the dataset: each one is locked while an administrator edits it.
Resource types
Section titled “Resource types”All the shapes form a single entity, shown in the Resource types tab. Each resource type, a SHACL node shape, and each field, a property shape, has its own page. These are the same pages HERITRACE uses for the data, so every change has a history and any past version can be restored.
The form checks each field as you fill it in, with the same rules that HERITRACE applies to the data. Each save then checks the whole set of shapes, not only the part you changed: when the result is not valid, such as a label query that uses an undeclared prefix, HERITRACE shows the reason beside the field it concerns and stores nothing.
The pages of the configuration do not offer to delete it, nor any of its resource types or fields.
