Usage¶
Resource definitions¶
The FAIR Data Point reference implementations introduces the concept of Resource Definitions. A resource definition captures housekeeping data about a metadata resource.
Resource definitions can be accessed from the reference implementation user interface, in the dashboard of an admin user. Here the resource definitions can be managed.
Managing resource definitions¶
Resource definitions can be created, modified, or deleted.
Creating resource definitions¶
When creating a new resource definition, the user interface presents you a form where a resource can be defined through a number of properties.
Name defines the human readable name for a resource definition. This name is used in the admin dashboard to identify the definitions, and does not affect a definition on the functional level. For example, for the default dcat:Dataset
resource, the human readable name would be "Dataset"
.
URL Prefix defines the URL path for a resource. This context path should be a unique identifier, unique in the scope of the other resource defined within the FAIR Data Point instance. For example, for the dcat:Dataset
resource the prefix is dataset
.
Target Class URIs links the shape definitions to a resource definition. In the current implementation, each shape that should be applied to the resource must be listed here. The expected URI value must match the sh:targetClass
value of the shape definition. A common example is to list the dcat:Resource
shape target class along with the specific subclass for the resource, like dcat:Dataset
.
Children defines child resources, if any. This applies when the resource acts as a parent resource for other types of resources. Children are defined by the following properties to provide directives for both the server and the client side.
Child Resource links to the child’s resource definition. The child resource must be defined beforehand.
Child Relation URI defines the predicate IRI that links the parent to the child on the metadata instance level. A common example is the link from a
dcat:Dataset
to adcat:Distribution
; these resources are linked by thedcat:distribution
predicate.Child List View Title defines a literal value to be displayed as a section header for the child resources in the user interface.
Child List View Tags URI defines the predicate IRI for values that are displayed in the user interface whenever the child resources are listed. A common example is
dcat:theme
fordcat:Dataset
resources.Child List View Metadata defines predicate IRIs for values that are listed in the child resource summary.
External links defines predicate IRIs and literal values to be displayed in the user interface for primary interaction with a resource. A common example is for the dcat:Distribution
resource, dcat:accessURL
is mapped to an Access URL
literal, and displayed prominently in the user interface.
Modifying resource definitions¶
When modifying a resource definition, not all properties are writable. Some properties are write-protected to ensure the internal consistency of the system.
The URL Prefix and the Target Class URIs are not writable.
The other properties, like child resources and external links are writable, and can be expanded or modified after the initial creation of the resource definition.
Deleting resource definitions¶
Deleting a resource definition should be used with caution. Existing metadata instances are no longer accessible after the resource definition is deleted. This includes child resources, if those are not linked to other resources.
Shapes¶
The FAIR Data Point reference implementation uses SHACL to add validation constraints to the metadata model.
Creating a new shape¶
A typical resource shape contains the following key elements:
sh:targetClass
to indicate the type of resource the shape applies tosh:property
for each resource propertysh:path
defines the predicate IRIsh:nodeKind
/sh:datatype
defines the object typesh:minCount
/sh:maxCount
defines the property cardinality
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix dash: <http://datashapes.org/dash#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix ex: <http://example.com/> .
:MyResourceShape a sh:NodeShape ;
sh:targetClass ex:MyResourceType ;
sh:property [
sh:path ex:value ;
sh:nodeKind sh:Literal ;
sh:minCount 1 ;
sh:maxCount 2 ;
] .
User interface directives¶
The DASH vocabulary introduces extensions to the core SHACL model. One of the extensions is focused on providing user interface hints for shape properties. Introducing or removing a dash:viewer
or dash:editor
property to a sh:PropertyShape
instance influences how the user interface displays the property value.
sh:property [
sh:path ex:value ;
sh:nodeKind sh:Literal ;
dash:viewer dash:LiteralViewer ;
dash:editor dash:TextFieldEditor ;
]
By adding a dash:viewer
statement, the user interface is instructed to show the property value when the resource metadata is displayed. Removing a dash:viewer
statement will instruct the user interface will not render the property value at all. The value will still be present in the metadata model. The supported set of viewers:
sh:LabelViewer
sh:URIViewer
By adding a dash:editor
statement, the editor form in the user interface will show an edit field for the property. Removing a dash:editor
statement will prevent the property from being edited. This could be intended behaviour for properties that are generated server side. The supported set of editors:
sh:TextFieldEditor
sh:TextAreaEditor
sh:URIEditor
sh:DatePickerEditor
Extending an existing shape¶
Extending an existing shape can be achieved by targeting the same sh:targetClass
. For example, to extend the existing dcat:Dataset
shape, an extension shape could look like the following:
:MyExtension a sh:NodeShape ;
sh:targetClass dcat:Dataset ;
sh:property [
sh:path <http://example.com/vocab#myProperty> ;
sh:nodeKind sh:Literal ;
sh:minCount 1 ;
] .
Limitations¶
The current implementation does not provide proper support for overriding properties when an existing resource is extended
The set of supported
dash:viewer
anddash:editor
types does not cover the full range as specified in the DASH specs.