Skip to main content

Managing Collections

Here below we are going to talk about 2 parts of the configuration of a collection, namely the "admin triples" and the "ext folder". To clarify, and even though they are linked, those config tend to have distinct responsibilities and update flows:

  • the ext folder is mostly about configuring data flow, indexation, access rights, etc. and is not much linked to the data model the collection represents. As such, when the data model evolves, it is usually not necessary to go and fiddle with those files. Unless there are specific needs that need to be addressed with the changes to the data model, like uri generation or computation of the label facet.
  • the admin triples contain a few config entities like connections to elastic or a triple store, but the core of it is mostly the shapes graph within.

Creating a collection from scratch​

First, you will need to add a dedicated folder in the ext/collections/ folder of Hanami. For this, we advise to start with our documentation about such folder. An example .zip is given at the start of the page to help you quickstart the creation with an example person collections. Here we will consider that you have created a folder called person-collection. Also, once your config files are set, be sure to restart Hanami, as it does not handle hot-reload of configuration files.

2. Add Collection Triples in the Admin Workspace​

Now that the collection is configured, it is time to actually create the collection in the admin workspace. This can be done by going through the UI from the home page, selecting the "Admin Workspace", then the "Collections" collection and clicking on the "Create Item" button. Then one can create that collection directly trough the form, or by uploading a file, like the one below. We do advise to start with a file upload as the form of a collection could be a bit complex to apprehend at first glance.

person.collection.ttl
@base <https://hanami.app/shacl/person/> . # the base uri can be changed to match the org base oe any other

@prefix dct:                     <http://purl.org/dc/terms/> .
@prefix ex:                      <http://example.com/> .
@prefix hanami:                  <https://hanami.app/ontology#> .
@prefix sh:                      <http://www.w3.org/ns/shacl#>.
@prefix xsd:                     <http://www.w3.org/2001/XMLSchema#>.


# The collection itself, the uri is not important as far as hanami is concerned
<collection>
    a                         hanami:Collection ;
    dct:title                 "Persons"@en, "Personnes"@fr ;
    dct:created               "2025-03-14T12:00:00Z"^^xsd:dateTime ;
    dct:modified              "2025-03-14T12:00:00Z"^^xsd:dateTime ;
    # unique id of the collection, make sure that it matched the name of the collection folder in the ex/collections folder
    dct:identifier            "person-collection" ;
    # List of node shapes available in the shapes graph describing the collection forms.
    hanami:shapes             <Person> ;
    # the rdf store used as the source of data for the collection. https://data.hanami.app/config/rdfstore/1 itself is reserved for the internal Jena triplestore and should not be used for business objects.
    hanami:rdfStore           <https://data.hanami.app/config/rdfstore/2> ;
    # the elasticsearch instance used to index the collection items. Usually there is only one elasticsearch instance per hanami instance, and so the uri is the same for all collections.
    hanami:elasticsearch      <https://data.hanami.app/config/elastic/1> ;
    # the workspace used to store the collection in.
    hanami:workspace          <https://data.hanami.app/config/workspace/data> ;
    # the base uri used to generate the uri of the collection.
    hanami:baseUri            "https://example.org/data/person/" ;
.

# Person
<Person>
    a              sh:NodeShape ;
    sh:targetClass ex:Person ;
    sh:name        "Person"@en, "Personne"@fr ;
    # Means that this node shape (and so related sh:targetClass) is used as the root node when a new item is created
    hanami:isRoot  true ;
    sh:property    <Person/name> ;
    hanami:viewer [
        a               hanami:TemplateViewer ;
        hanami:template "{{label 'http://example.com/name'}}" ;
    ]
.

<Person/name>   
    a           sh:PropertyShape ;
    sh:path     ex:name ;
    sh:nodeKind sh:Literal ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:name     "Name"@en, "Nom"@fr ;
    sh:order    1 ;
.

3. Go an create an Item for the new Collection​

Now that you have a properly configured collection, it is time to actually create an item within it! For this, you should navigate to that collection going through the workspace that it belongs to (for example a "Data" workspace).

Updating a Collection​

Depending on which part of the config of a collection you are touching, there different things that can be done:

  • config files in the ext folder: for those, whenever you change a file in there, you will need to restart Hanami so that changes are taken into account. Depending on what you have changed, you might want to trigger a reindex on that collection after Hanami boots up.
  • config triples: here things are a bit smoother. Regardless of the way you update the collection triples (more on this below), the changes are taken into account automatically, and so you would see your changes reflected on the form of a related items. If the changes made are expected to have changes on the validation constraints, you should also trigger a reindex so that the health score of items within that collection are computed again to take into account the new constraints.

Multiple ways to update a collection​

Most shacl properties and other collection triples can be updated through the UI, and after the changes are saved, all forms related to that collection will be updated. But some shacl properties are not yet available to be edited through the UI, or the UI for those might feel cumbersome. For those cases, one could do a manual update of the associated collection graph. To do so, one would:

  1. Go on the form of the related collection
  2. Click on the actions menu button to download the current collection graph (can be any format, .ttl is advised)

fig 1: download collection graph

  1. Update the downloaded file with the desired changes to the shapes or other triples
  2. Upload the updated file by going into the "Collections" collection, and trigger an item creation by file upload.
  3. You should be prompted with a confirmation box to confirm that the upload will override the current collection graph. Click on "Yes" to confirm and trigger the update.

After that, you can go on a form of any entity handled by this collection (e.g. the form of a ex:Person) and see the effects of your changes.

info

This way of updating an item through file upload works for any type of item, not only collections!

Incorporating Shapes Graphs from outside of Hanami​

If you maintain a shapes graph outside of Hanami and its internal triplestore, then to update a related collection with a new version of its shapes graph, the easiest would be to go through the download/upload procedure as explained above, replacing the shapes graph triples with the new ones. Just beware that if node shapes were removed or added, the hanami:shapes predicate on the hanami:Collection instance need to be updated accordingly.