Skip to main content

Collections Configuration

In the ext/collections folder, there is a folder for every collection containing its configuration. The name of a given folder should exactly match the dct:identifier of a given collection. Collections represent logical groupings of RDF resources that share common characteristics. The structure of these folders is described here after, taking as example the person-collection collection.

Select-Root.sparql​

The select-root.sparql file contains a SPARQL SELECT query that identifies the root item from a model. This is important for traversing the RDF graph and establishing the entry point node of an item within a collection. For example one could consider an item being a skos:ConceptScheme and all its skos:Concept. Then the root node would be the skos:ConceptScheme node. In the example collection, we just consider all ex:Person to be the root nodes.

select-root.sparql
prefix ex:      <http://example.com/>

select ?uri {
  ?uri a ex:Person .
}

This query is run within the context of a single item, so this is why we do not use any graph ?g in the query.

Actions Folder​

The actions folder contains YAML files configuring actions to be executed on certain events. These actions can trigger SPARQL updates, notifications, or other operations when specific events occur on items of the collection.

TODO: document available actions configuration

Index-Hanami Folder​

The index-hanami folder contains indexing configuration that defines how RDF data is indexed for search and retrieval. It has the following structure:

select-items.sparql​

The index-hanami/select-items/select-items.sparql file contains a SPARQL query that is run to find all uri of nodes that are root to be indexed in hanami's elastic instance. This query has to select ?uri, and usually follows the same logic as the select-root query, but here the context is the whole triplestore the collection is linked to, so here we have to use graph ?g.

index-hanami/select-items/select-items.sparql
prefix ex:      <http://example.com/>

select ?uri {
  graph ?g {
    ?uri a ex:Person
  }
  filter (str(?g) = concat(str(?uri), "/graph"))
}

The filtering on the graph uri is done to ensure that we only index items that are part of the collection and follow the expected convention, so that we do not embed triples that come from other graphs when indexing the items. Depending on the use case, this might not be needed.

select-quads.sparql.spel​

The index-hanami/select-items/select-items.sparql.spel file contains a templated SPARQL query that uses SpEL (Spring Expression Language) expressions. In this template the uris resulting of the select-items query are injected using the uriList variable. Here the logic is to select all quads belonging to each uri to embed related quads in indexed documents.

index-hanami/select-quads/select-quads.sparql.spel
prefix ex:      <http://example.com/>

select ?g ?s ?p ?o {
  graph ?g {
    ?uri a ex:Person.
    filter(?uri in #{[uriList]})
    ?s ?p ?o
  }
  filter (str(?g) = concat(str(?uri), "/graph"))
}

facets Folder​

The facets folder contains facet queries to create faceted properties on elastic documents. Those properties are used in the Hanami UI to display custom properties, display labels or execute full text search. For now, we have a limited sets of facets that are automatically picked up by hanami, described in the sections below.

The names of the files within this folder are not important, they just needs to be *.spel files and they will be picked up by hanami automatically.

label​

The label facet is used to display the label of an item and to perform text search on it. Here is an example on how to compute it for an item that uses ex:name as the property being used for the label of that entity:

index-hanami/facets/01-label.sparql.spel
PREFIX ex:     <http://example.com/>

select distinct
  ('hanami' as ?groupName)
  ('label' as ?facetName)
  ?language
  ?label
{
  <#{[uri]}> ex:name ?label.
  bind(lang(?label) as ?langTemp).
  filter(strlen(?langTemp) = 2 || ?langTemp = "")
  bind(
    if(?langTemp = "", "UNKNOWN", ?langTemp) as ?language
  )
}

The important part is the select clause, which is used by hanami to properly build the structure of that facet in elastic. Not following this convention will most likely result in errors on text search. The convention is:

  • ?groupName has to be 'hanami'
  • ?facetName has to be 'label'
  • ?language is the language of the label and should be a string like 'en', 'fr', 'de', etc. If the associated language is not known, please fallback to 'UNKNOWN'.
  • ?label is the label of the item and should be a string.

It is to be noted that multiple *.spel files in the same collection could be defined, all fo them trying to compute the label facet of an item, or one of its nodes. In such case, it is advised to work with clearly defined filter clauses to avoid conflicts.

elastic settings​

The elastic-settings.json file contains the settings for the Elasticsearch index for this collection, including mappings, analyzers, and other Elasticsearch-specific configurations. It is advised to take the example config as-is for any new collection, unless you have very specific needs. For more information on elastic config, please take a look at the elastic documentation.

Operations Folder​

The operations folder contains a file called roles.json5. This is used to configure which role a user should have to perform certain actions on the collection. The definition of the roles can be found in ext/operations/operations.json5. This implements a fine-grained authorization system based on roles and operations and should always be the same for system making use of WAC, as we usually just set those up for super-admins to be able to do anything on the system.

operations/roles.json5
{
  "roles": {
    "ADMIN": [
      "crud-download/create-check",
      "crud-download/read-check",
      "crud-download/update-check",
      "crud-download/delete-check",
      "crud-download/download-check"
    ]
  }
}

URI-Generator Folder​

The uri-generator folder contains uri-generator.json5 configuring how URIs should be generated for the collection when users create new items or nodes within an item.

uri-generator/uri-generator.json5
{
  prefixes: {
    ex: "http://example.com/",
  },
  generators: [
    {
      id: "persons",
      uriSelector: "select distinct ?uri {                                            \
                      ?uri a ex:Person                                                    \
                    }",
      variableSelector: "select ?uuid { bind(struuid() as ?uuid) }",
      uriTemplate: "#{[baseUri]}#{[uuid]}",
    },
  ],
}
  • the prefixes are used for all queries defined withing the document
  • generators is an array of uri generation configs, there can be as many as desired, depending on th desired logic. Each generator has:
    • id: the id of this generator, ideally unique and mostly used for debugging purposes.
    • uriSelector: selects the (temporary) uris that need to be replaced. When a user creates a new node, its uri will always start with http://resource/ to mark it as temporary, and only those uris are being replaced. For example here above, we only implemented the uri generations for nodes of type ex:Person, but it does not need to be this restrictive.
    • variableSelector: selects the variables that will be used to generate the uri. Here we just use a random uuid, but it could be any other combination of other variables, like sequence number, kebab-cased types or anything else.
    • uriTemplate: the template to use to generate the uri. By default, baseUri is the hanami:baseUri defined in the collection, all other variables are coming from the variableSelector query.