Extra configuration

Unfortunately, SHACL (SHACL Core, including its extended features for SPARQL and node expressions, and SHACL UI) cannot express every aspect of the editor that we consider important. The aspects it leaves out are configured in the YAML file described here: which entity types and fields are visible, how values are ordered and searched, how proxy relationships work, how the catalogue sorts entities and how duplicates are found.

File location

The application reads the YAML file from /app/display_rules.yaml inside the container. To use your own file, mount it as a Docker volume:

volumes:
  - ./my_display_rules.yaml:/app/display_rules.yaml

Example configurations are available in example_configurations/.

Core concepts

The configuration is a list of rules. Each rule targets entities by class, by SHACL shape or by both, and defines how those entities and their properties should be handled.

Targeting entities

You can target entities with rules in three ways, allowing for granular control.

By Class

You can target all entities of a specific RDF class.

# Targets all entities that are a fabio:JournalArticle
- target:
    class: "http://purl.org/spar/fabio/JournalArticle"
  # ... other settings

By SHACL Shape

You can target entities that conform to a specific SHACL shape. This is useful for distinguishing between entities of the same class that have different characteristics (e.g., a standard issue vs. a special issue).

# Targets all entities that conform to SpecialIssueShape
- target:
    shape: "http://schema.org/SpecialIssueShape"
  # ... other settings

By Class and Shape

For maximum precision, you can target entities that belong to a specific class AND conform to a specific shape.

# Targets entities that are a fabio:JournalIssue AND conform to RegularIssueShape
- target:
    class: "http://purl.org/spar/fabio/JournalIssue"
    shape: "http://schema.org/RegularIssueShape"
  # ... other settings

When an entity could be targeted by multiple rules (e.g., it has multiple types), the rule with the lower priority number is applied.

- target:
    class: "http://purl.org/spar/fabio/JournalArticle"
  priority: 1 # Higher priority
  # ...
- target:
    class: "http://purl.org/spar/fabio/Expression"
  priority: 2 # Lower priority
  # ...

Key rule settings

Here are the top-level settings for each rule, listed in order of how they are presented in this documentation:

• priority: Decides which rule applies when several rules match an entity. See Targeting entities.
• shouldBeDisplayed: A boolean that defaults to true. If false, this entity type does not appear in the catalogue or on the “Add” page.
• displayProperties: A list defining how each property of the entity should be displayed and behave. See the Configuring properties section for details.
• sortableBy: A list of properties that users can use to sort items in the catalogue view. See the Sorting catalogue items section for details.
• similarity_properties: A configuration that defines which properties are used to identify potential duplicate entities. HERITRACE uses these to display “Similar Resources” on entity pages, enabling users to merge duplicates. See the Similarity properties for duplicate detection section for details.

Configuring properties (displayProperties)

This is where you define the behaviour of each field of an entity. Each entry names a property with property and lists only the settings that differ from the defaults.

Visibility

- property: "http://purl.org/spar/datacite/hasIdentifier"
  shouldBeDisplayed: false

• shouldBeDisplayed: Defaults to true. If false, the field is hidden in forms.

Search and disambiguation

You can enable real-time search to prevent duplicate entries.

- property: "http://purl.org/dc/terms/title"
  supportsSearch: true
  minCharsForSearch: 3

• supportsSearch: Set to true to enable search-as-you-type.
• minCharsForSearch: The number of characters a user must type before the search is triggered. Defaults to 4.
• searchTarget:
  • self (default): Searches for entities of the same type with a matching property value (e.g., finding other articles with a similar title).
  • parent: Use this when a property links to a separate but related entity. This setting ensures that a search for the related entity’s value returns the main (parent) entity. For example, if a bibliographic resource is linked to an Identifier entity (which holds a DOI), a search for the DOI value should return the resource itself, not the Identifier entity.

Ordering items (orderedBy)

When the order of multiple values for a property is significant (e.g., the sequence of authors for a paper), you can use the orderedBy key. It specifies the RDF predicate that defines this order. When orderedBy is configured, the interface will display drag-and-drop handles, allowing users to reorder the items manually.

- property: "http://purl.org/spar/pro/isDocumentContextFor"
  orderedBy: "https://w3id.org/oc/ontology/hasNext"
  # ... other settings

How it works: RDF representation

When a user arranges items, HERITRACE uses the specified orderedBy property to create a linked list that connects the items sequentially. This approach is model-agnostic; it can order any set of related resources, whether they are direct properties or linked through an intermediate proxy entity.

For instance, if a resource has multiple related items and their order matters, the RDF structure would look like this:

@prefix ex: <http://example.org/ontology/> .
@prefix : <http://example.org/instance/> .

# :myResource is linked to three items.
# The order in this triple declaration is not significant.
:myResource ex:hasItem :item1, :item2, :item3 .

# The 'orderedBy' property (ex:hasNext) creates a chain.
:item1 ex:hasNext :item2 .
:item2 ex:hasNext :item3 .

# :item3 has no ex:hasNext, marking it as the end of the list.

Work in Progress

Currently, HERITRACE supports modeling order using a sequential property to form a linked list. We plan to support other ordering patterns, such as using an index property, in future releases.

Relationship properties (proxy pattern)

Sometimes a simple link between two entities isn’t enough. You might need to describe the relationship itself. For example, a person can be an author of an article, but they could also be an editor. How do you capture this specific role?

This is solved with a Proxy Pattern, which uses an intermediate entity to hold the properties of the relationship.

The data model looks like this: Journal Article → isDocumentContextFor → Role In Time → isHeldBy → Person

The Role In Time entity is the “proxy.” It holds the details, like the specific role (pro:author or pro:editor).

Here is how you configure this complex relationship in display_rules.yaml:

- property: "http://purl.org/spar/pro/isDocumentContextFor"
  orderedBy: "https://w3id.org/oc/ontology/hasNext" # Optional: property to sort items
  intermediateRelation:
    class: "http://purl.org/spar/pro/RoleInTime"
    targetEntityType: "http://xmlns.com/foaf/0.1/Agent"

Breaking down the configuration:

• property: The property on the source entity (Journal Article) that points to the proxy entities.
• orderedBy: (Optional) Specifies a property used to create an ordered sequence between the proxy entities, ensuring they are displayed in the correct order (e.g., for a list of authors). When orderedBy is used, HERITRACE displays drag-and-drop handles next to each item, allowing users to reorder them manually.
• intermediateRelation: This is the core of the proxy configuration.
  • class: The rdf:type of the proxy entity (pro:RoleInTime).
  • targetEntityType: The rdf:type of the final entity you want to link to (foaf:Agent). HERITRACE uses this to know what kind of entity to create or search for. Authors and editors are both pro:RoleInTime entities, but they conform to different shapes (AuthorShape, EditorShape). The SHACL shape of the article declares one property shape for each role, with its own sh:name, so HERITRACE shows them as separate groups. Each role is shown with the label of its shape, and the link opens the agent reached through the proxy.

Sorting catalogue items (sortableBy)

The sortableBy configuration allows users to sort entities in the catalogue view by specific properties. When configured, sorting controls appear in the catalogue and recycle bin interfaces, letting users organize items by properties like title, publication date, or any other relevant field.

Basic configuration

- target:
    class: "http://purl.org/spar/fabio/JournalArticle"
  sortableBy:
    - property: "http://purl.org/dc/terms/title"
      sortOrder: ["asc", "desc"]
    - property: "http://prismstandard.org/namespaces/basic/2.0/publicationDate"
      sortOrder: ["desc", "asc"]

Configuration options:

• property: The URI of the property to sort by. The sort control shows the sh:name of the property.
• sortOrder: An array defining available sort directions. The first value is the default.
  • "asc": Ascending order (A-Z, 0-9, oldest-newest)
  • "desc": Descending order (Z-A, 9-0, newest-oldest)

Performance Optimization: Omitting sortableBy

For large datasets with thousands or millions of entities, consider omitting the sortableBy configuration entirely. When no sorting properties are defined, HERITRACE does not apply any ORDER BY clause to the SPARQL queries that retrieve entities for the catalogue view.

Similarity properties for duplicate detection

The similarity_properties configuration enables HERITRACE to identify potential duplicates when users create or view entities. When configured, the system automatically searches for similar resources based on matching property values and displays them in the “Similar Resources” section on entity pages, where users can initiate merge operations.

How similarity detection works

HERITRACE queries the triplestore to find other entities of the same type that share matching values for the configured properties. The configuration supports boolean logic combining OR and AND conditions.

Basic configuration

The simplest configuration uses OR logic: entities are considered similar if they match on any of the specified properties.

- target:
    class: "http://purl.org/spar/fabio/JournalArticle"
  similarity_properties:
    - "http://purl.org/dc/terms/title"
    - "http://purl.org/spar/datacite/hasIdentifier"

This configuration finds articles that share either the same title or the same identifier. For instance, if a user views an article titled “Machine Learning Applications”, HERITRACE will find other articles with that exact title or with matching identifiers.

AND logic for stricter matching

For more precise duplicate detection, you can require that multiple properties match simultaneously using AND logic.

- target:
    class: "http://purl.org/spar/fabio/JournalIssue"
  similarity_properties:
    - and:
      - "http://purl.org/spar/fabio/hasSequenceIdentifier"
      - "http://purl.org/vocab/frbr/core#partOf"

This configuration only considers issues as similar if they have both the same sequence identifier (e.g., issue number) and belong to the same journal. This prevents false positives where different journals might use the same issue numbering scheme.

Complex matching with combined logic

You can combine OR and AND logic.

- target:
    class: "http://xmlns.com/foaf/0.1/Agent"
  similarity_properties:
    - "http://xmlns.com/foaf/0.1/name"
    - and:
        - "http://xmlns.com/foaf/0.1/familyName"
        - "http://xmlns.com/foaf/0.1/givenName"
    - "http://purl.org/spar/datacite/hasIdentifier"

This configuration for agents (people or organizations) considers entities similar if they match on:

• The same full name (foaf:name), OR
• Both the same family name AND given name, OR
• The same identifier (e.g., ORCID)

Best practice: keep it DRY with YAML anchors

To avoid repeating the same property definitions, use YAML anchors (&) and aliases (*). HERITRACE reads only the rules key, so other top-level keys can hold the anchors.

# 1. Define reusable properties at the top
common_properties:
  title_property: &title_property
    property: "http://purl.org/dc/terms/title"
    supportsSearch: true
    minCharsForSearch: 2

# 2. Use aliases in your rules
rules:
  - target:
      class: "http://purl.org/spar/fabio/JournalArticle"
    displayProperties:
      - *title_property
  - target:
      class: "http://purl.org/spar/fabio/Book"
    displayProperties:
      - *title_property

Virtual properties: Bridging user mental models and data models

Sometimes, the way data is structured in your RDF ontology doesn’t align with how users naturally think about it. Virtual properties are HERITRACE’s solution to this mismatch, allowing you to present data in a way that matches users’ mental models while maintaining the integrity of your underlying data model.

The problem: Ontological vs. intuitive representation

Consider citations. In the CITO ontology, a citation is modeled as a first-class entity (a cito:Citation class) that links two bibliographic resources:

:citation1 a cito:Citation ;
    cito:hasCitingEntity :articleA ;
    cito:hasCitedEntity :articleB .

This is ontologically sound and enables rich metadata about citations (citation type, semantics, etc.). However, most users think of citations as relationships, not entities. When editing an article, users expect to simply “add a citation” to another resource, not “create a Citation entity that links this article to another resource.”

The solution: Virtual properties

Virtual properties let you hide the complexity of the underlying data model and present a simpler, more intuitive interface. When a user adds a value to a virtual property, HERITRACE automatically creates and manages the intermediate entities behind the scenes.

For the citation example, you can configure:

• A “Citations” virtual property that appears as a simple relationship field
• When the user adds a citation, HERITRACE creates the Citation entity automatically
• The user never sees or manages the Citation entity directly

You can even show both directions of the relationship (“Citations” and “Is Cited By”) as separate virtual properties, even though they’re backed by the same set of Citation entities in the graph.

Learn more

For detailed configuration instructions, complete examples, and best practices, see the Virtual properties configuration guide.