Skip to content

Extensions

Jump to bottom
Simon Oakes edited this page May 16, 2023 · 16 revisions

These notes cover additional features that are not yet part of the API specification. They are, or are planned to be, implemented in the proof-of-concept system and may be added to the main API in the future.

Contents

Graph registration

In the normal API a managed entity is a resource with associated properties (a closed bounded description). There are circumstances where we would like to be able to store a complete graph that describes multiple resources without have to create tracked item registrations for each of the contained resources. For example, we would sometimes like to be register a complete Ontology (using #-URI patterns) with the Ontology itself corresponding to the managed entity.

We support this through the ?graph flag which enables us to register a complete graph as a payload. To cater for the lack of unique root a graph must be registered through a PUT directly to the entity uri.

Action URI Payload Response
PUT /register/entity?graph RDF graph containing some assertions about /register/entity 201 if the graph is successfully created

If the item correspond to the entity URI does not exist then this is treated as a registration and the item is created. If the item does exist then this is treated as an update to the entity, creating a new versioned resource.

Graph annotation

A related but distinct situation occurs when we wish to annotate an item with some complex derived metadata which cannot be treated as simple properties of the item. An example is the results of a deep analysis of a registered dataset.

This is supported though the ability to annotate a registered item with a graph of data.

Action URI Payload Response
PUT /register/_item?annotation=graphname RDF graph to store as an annotation 201 if the graph is successfully created
GET /register/_item?annotation=graphname The stored annotation graph

The annotation request stores the RDF payload as in a graph whose name matches that of the URI in the PUT/GET requests. The register item itself is also updated to record the existence of the annotation graph:

</register/_item> a reg:RegisterItem;
    reg:annotationGraph </register/_item?annotation=graphname> .

Typed templates

By default when a registered item is viewed the default tab shows the RDF properties of the entity as a table of property/value pairs. Other tabs show the item metadata and the history of changes to the item.

To support customizable views of particular entity types, such as VoID data sets (see below) an experimental system of typed templates is provided.

A new system register /system/typed-templates holds the list of registered templates. Each registered template provides a description of a single template comprising an RDF type which can trigger it, the name of a Velocity template which will perform the rendering and a priority. For example:

@prefix ui:   <http://purl.org/linked-data/registry-ui#> .

<concept-scheme> a ui:Template;
    rdfs:label "concept scheme template";
    ui:template "concept-scheme-render.vm";
    ui:templatePriority 50;
    ui:type skos:ConceptScheme;
    .

Items often have several different types, which may mean that multiple typed templates can match. The matching template with the highest priority number will be used.

The template itself cannot be dynamically uploaded the registry remotely, for security and stability reasons. A registry instance can configure the file system area in which templates are stored and can provide separate facilities for dynamically adding template files to this area if such facility is desired.

Messaging and notification

The conceptual design of the UKGovLD Registry includes the idea that a change of state to the contents of the registry may trigger some external agent to analyse the registry contents in the context of the change (e.g. identifying new linksets when a dataset is registered and adding the appropriate annotations, or maintaining SKOS broader or narrower relationships between Concepts etc.). Alternatively, changes may be captured and replayed in read-only mirror copies of the register within a distributed deployment.

To meet this requirement, an internal messaging service has been implemented.

Any command which involves a change of state (Register, Update, StatusUpdate, Annotate) notifies the message service. It passes the details of the command (the target URI, operation done, including for the registration command the RDF payload). These are packaged up into a Message object, a copy of which is broadcast to all registered listeners.

The registry also supports sending messages to external message brokers using the STOMP message protocol and custom plugins. See the Notification page for full documentation of this feature.

Hierarchical Views

Registers often contain information that could be usefully viewed as a hierarchy. For example, it is common to have a SKOS Concept Scheme that uses broader/narrower links to relate the concepts hierarchically. Note that this is separate from the URL hierarchy of the registers themselves, the URIs for each concept in a hierarchical concept scheme will normally all be in a single register and so all rooted at the same base URI.

The default registry UI provides a simple tree view for such hierarchical registers and can switch between list and tree views.

To declare that a register can be viewed hierarchically you attach two properties to the register itself which between them define the hierarchical structure. The properties available for this are summarized below.

Property Meaning
ui:hierarchyChildProperty Specifies a path from a parent node in a hierarchical register to a child node. If the value of this property is a resource then it assumed to be a simple direct property (e.g. skos:narrower or org:hasSubOrganization). If it is a literal then it is assumed to be a syntactically legal SPARQL path expression that can be used to navigate from the parent to the child.
ui:hierarchyRootProperty For a register that can be viewed as a hierarchy, the value of this property gives a property possessed by any root entries. The value that such a property has is not relevant, though a common pattern is to use skos:topConceptOf in which case the value will be the register itself.
ui:hierarchyRootType For a register that can be viewed as a hierarchy, the value of this property indicates the rdf:type of those entries which should be considered roots of the hierarchy.

For a register to be viewed hierarchically it must provide a value for ui:hierarchyChildProperty and a value for one of ui:hierarchyRootProperty or ui:hierarchyRootType.

Clone this wiki locally