Application configuration
Any unique instance of shacl-vue
can be tailored to its specific use case and users through a custom configuration. This includes required instance inputs, such as the URLs to the input sources covered in the Application Inputs section, as well as various settings for theming, identifiers, UI behavior, and service API integration.
Configuration is done via a config.json
file, available at shacl-vue/public/config.json
Current configuration options include:
General app settings
{
"app_name": "",
"page_title": "",
"documentation_url": "",
"source_code_url": "",
"footer_links": [
{
"url": "",
"text": ""
}
]
}
app_name
is the name of the application displayed in the browser tab and UIpage_title
is the title for the HTML pagedocumentation_url
is the URL of the user documentation for the specificshacl-vue
instancesource_code_url
is the URL of the source code repository for the specificshacl-vue
instancefooter_links
is an array of objects, where each object contains theurl
and displaytext
for a link that should be included in the application footer
The HTML page title of the main application is set in shacl-vue/src/components/ShaclVue.vue
based on values in the configuration file (config.json
). The app uses the following priority when setting the title:
- IF
page_title
is defined, use it; - ELSE IF
app_name
is defined, use it; - ELSE, fallback to "shacl-vue".
URLs should be unique and resolvable online URIs.
Theming settings
{
"app_theme": {
"link_color": "",
"hover_color": "",
"active_color": "",
"vistied_color": "",
"panel_color": "",
"logo": "",
},
"front_page_content": ""
}
Colors schemes and application logo can be set via the app_theme
option:
link_color
is the default link colorhover_color
is the link hover coloractive_color
is the link active state colorvisited_color
(Optional) is the visited link colorpanel_color
is the background color of the main left-hand-side UI panel displaying all data typeslogo
is the path to the logo used in the HTML page header. The logo path should either be a unique and absolute online URI, or a path relative toshacl-vue/public
in the case of a file local to the repository.
All colors should be defined using hexadecimal color codes (#RRGGBB).
The front_page_content
option allows the inclusion of arbitrary HTML content as the front page of a shacl-vue
deployment, which will display when no data type is selected from the left-hand-side panel. The front_page_content
option should contain the name of the HTML page to be included (e.g. frontpage.html
), the file content should be standard HTML wrapped in <html></html>
tags, and the file itself should be placed in the root distribution directory of the deployment.
Application inputs sources
{
"shapes_url": "",
"use_default_shapes": false,
"data_url": "",
"use_default_data": false,
"class_url": "",
"use_default_classes": false,
}
shapes_url
is the URL to fetch the shapes graph fromdata_url
is the URL to fetch the data graph fromclass_url
is the URL to fetch the class hierarchy fromuse_default_shapes
,use_default_data
, anduse_default_classes
specify using default demo files as fallback config URLs, whentrue
All application input source URLs should either be unique and absolute online URIs, or a path relative to shacl-vue/public
in the case of a file local to the repository. These URLs should return documents in TTL format.
The defaults for all input source URLs are the repository-local demo files.
Identifier settings
{
"id_iri": "https://concepts.datalad.org/s/things/v1/pid",
"id_autogenerate": {
"": {
"id_autogenerate_prefix": "",
"id_autogenerate_prepend": ""
}
},
"id_resolves_externally": [],
"prefixes": {
"": ""
}
}
id_iri
is the URI of the property that indicates the persistent identifier of an entity. It is central to the functioning ofshacl-vue
because it allows for the mapping between structured records and the representation of those records as named nodes in RDF graphs. The value of this option is dependent on the SHACL schema driving theshacl-vue
instance. It defaults tohttps://concepts.datalad.org/s/things/v1/pid
since the demo input sources are created from thehttps://concepts.datalad.org/s/things/v1/
schema that implements that persistent identifier definition.id_autogenerate
is a dictionary mapping class IRIs to auto-generated identifier rules, and allows theshacl-vue
instance to auto-generate the value of theid_iri
-property (i.e. thePID
) of a manually created record of a particular class. The auto-generated value is determined from two more configuration options,id_autogenerate_prefix
andid_autogenerate_prepend
, and a random component.id_autogenerate_prefix
should be the name of a known prefix in the deployment (which can also be customized via configuration, seeprefixes
below), for exampledlthings
, andid_autogenerate_prepend
can be any string e.g. '/people'. The construction is then<resolved-prefix><prepended-string><random-string>
, where the random string part is generated with JavaScriptscrypto.randomUUID()
. For the given example strings, thepid
field for a new record created manually in ashacl-vue
instance will be:https://concepts.datalad.org/s/things/v1/people/<randomUUID>'
.id_resolves_externally
is an array of prefix strings. Records for which the PID includes any of these prefixes will resolve online, and additional UI will become visible that allows such records to be navigated to both inside the application and externally online. Included prefixes should be known prefixes in the deployment, i.e. they should arrive via the input sources that drive the application or can be included via configuration (seeprefixes
below).prefixes
is a JSON mapping from prefix to URI for prefixes used throughout ashacl-vue
instance. While most namespaces known to ashacl-vue
instance are derived from its input sources (SHACL schema, RDF data, class hierarchy information), this option allows additional prefixes to be supplied in order to support referencing external vocabularies and use-case specific naming conventions.
UI behavior
{
"show_shapes_wo_id": true,
"show_all_fields": true,
"show_classes": [],
"show_classes_with_prefix": [],
"hide_classes": [],
"hide_classes_with_prefix": [],
"no_edit_classes": [],
"allow_edit_instances": [],
"class_name_display": "",
"class_icons": {
"": ""
},
"editor_selection": {},
"editor_config": {},
"display_name_autogenerate": {},
"display_name_autogenerate_placeholder": {}
}
show_shapes_wo_id
shows data types (in the left-hand-side panel) for which the driving SHACL shapes do not have theid_iri
property defined, whentrue
show_all_fields
displays all properties in the form editor when a record is created/edited, whentrue
. Properties in the form editor are displayed by default in order of reverse inheritance. For example, if thePerson
class is derived from theThing
class, the form editor for aPerson
would display thePerson
-properties in top, and theThing
-properties below that. Often, only the top-level properties are of immediate interest or importance to users and UX is improved by hiding other properties. Theshow_all_fields
option, whenfalse
, would hide lower-level properties and display the top-level properties and required properties when a user opens the form editor to add/edit a record. In addition to the configuration option, the UI still allows the user to toggle between showing and hiding lower-level properties.show_classes
,show_classes_with_prefix
,hide_classes
, andhide_classes_with_prefix
are options that together specify which classes to show and hide in the left-hand-side panel listing all data types (i.e. classes):show_classes
: an array of class URIs that should all be shownshow_classes_with_prefix
: an array of prefixes, all classes containing any of these prefixes should be shownhide_classes
: an array of class URIs that should be hiddenhide_classes_with_prefix
: an array of prefixes, all classes containing any of these prefixes should be hidden
If both
show_classes
andshow_classes_with_prefix
are empty arrays, all classes are shown, apart from those inhide_classes
or those with prefixes inhide_classes_with_prefix
. Records that end up being hidden/excluded:- WILL NOT show up in the left-hand-side panel
- CANNOT be navigated to using URL query parameters
- by implication, CAN ALSO NOT be edited via URL query parameters
- CAN be created via
Add new item
button inInstancesSelectEditor
, i.e. the dropdown that allows users to select a specific record.
no_edit_classes
prevents records of specific classes from being created or edited by users. Records of these classes:- WILL show up in the left-hand-side panel, EXCLUDING the option to create new records
- CAN be navigated to using URL query parameters
- CANNOT be edited via URL query parameters
- CANNOT be created via
Add new item
button inInstancesSelectEditor
allow_edit_instances
, allows an edit button to be added for all instances in anInstancesSelectEditor
, i.e. the dropdown that allows users to select a specific record. This edit button allows the user to edit the specific record directly, without having to navigate to the record editor via the left-hand-side panel.allow_edit_instances
can take a boolean value oftrue
to apply this setting for all instances of all classes, or alternatively an array with specific class URIs to apply the setting only for instances of specific classes. The edit button will be disabled if the record's class is included inno_edit_classes
.class_name_display
specifies which format to use when displaying class names in theshacl-vue
UI. Allowed options are:- 'name': the value of the
sh:name
attribute in the class's nodeshape (e.g.Originating Agent
); this option is the default - 'reference': the reference of the class's nodeshape IRI in CURIE format (e.g.
Agent
); this option is used when 'name' is specified but thesh:name
attribute is not available - 'curie': the class's nodeshape IRI in full CURIE format (e.g.
prov:Agent
)
- 'name': the value of the
class_icons
is a mapping of class URIs to Material Design Icons. By default,class_icons
that are not defined will display as empty circles.editor_selection
: this option allows the UI to use config-driven selection of an editor component instead of the component matching procedure thatshacl-vue
uses by default. The object takes keys of a SHACL property shape as its keys in CURIE format (e.g.sh:datatype
,sh:path
, orsh:nodeKind
), and the values are objects themselves. These objects will have the to-be-matched CURIEs as keys, and the corresponding value should be the exact name of the component that will be selected. An example is provided below.editor_config
allows component-specific parameters to be passed to name-identified components. Such parameters allow the customization of behavior or display inshacl-vue
components. The object has the exact name of any editor component as its keys, and values are key-value parameter pairs that should feed into the associated editor components. An example is provided below.display_name_autogenerate
: by defaultshacl-vue
uses theskos:prefLabel
of a record, if available, as its display label. When not available, thedisplay_name_autogenerate
provides a means to autogenerate the display label of a record from a string serialization of other properties of the same record. This option should receive an object with class CURIEs as its keys and the values being string templates. Placeholders in such a template should be curly brackets containing the CURIE of a property of the class that should be used instead of the placeholder. See example usage below.display_name_autogenerate_placeholder
: when using thedisplay_name_autogenerate
option, it is possible that not all parameters in the template string exist as properties of an associated record for which a display label is being autogenerated. For such cases, the missing parameter will be replaced with a missing value placeholder string. This option allows for providing adefault
placeholder to be used for all missing values, or for providing a missing value placeholder per property. See example below.
Example
In the example below, the editor_selection
option specifies that, if a SHACL property shape is encountered where the sh:datatype
is equal to mydatetime:year
, the W3CISO8601YearEditor
should be selected and rendered. The editor_config
option specifies that, for the W3CISO8601YearEditor
, the yearStart
and yearEnd
options should be set to 1925
and 2077
, which for this component defines the starting and ending years that together make up the range of options in the rendered year-picker.
{
...
"editor_selection": {
"sh:datatype": {
"mydatetime:year": "W3CISO8601YearEditor",
}
},
"editor_config": {
"W3CISO8601YearEditor": {
"yearStart": 1925,
"yearEnd": 2077
}
},
...
}
In this example display_name_autogenerate
is used to generate a display label for records of class myns:TimeDuration
, specifically for cases where such records do not already have an existing skos:prefLabel
. The display label is generated by concatenating three values: the property myns:start_date
, the string " to "
, and the property myns:end_date
. If for example myns:start_date
is 2022-09-27
and myns:end_date
was missing in the data, then the generated display label would be 2022-09-27 to [*END]
. If the same was true, but the display_name_autogenerate_placeholder
config option did not contain the "myns:start_date": "[*END]"
key-value pair, then the generated display label would be 2022-09-27 to [X]
.
{
...
"display_name_autogenerate": {
"myns:TimeDuration": "{myns:start_date} to {myns:end_date}"
},
"display_name_autogenerate_placeholder": {
"default": "[X]",
"myns:start_date": "[*START]",
"myns:start_date": "[*END]"
},
...
}
Service API integration
While source data is specified in the Application Inputs section as one of the main inputs to a shacl-vue
instance, this input does not have to come from a single TTL-document via the data_url
configuration option. In fact, it is likely beneficial to many shacl-vue
instances to allow getting data from (and pushing data to) a separately and continuously maintained data source, using standard HTTP. An example of such a source is the Dump Things Service, which is supported by shacl-vue
via the use_service
and related configuration options.
{
"use_service": true,
"use_token": true,
"token_info": "",
"token_info_url": "",
"service_base_url": [
{
"url": "",
"type": ""
}
],
"service_endpoints": {
"": ""
},
"service_fetch_before": {
"": []
},
"service_constrained_search": {
"min_characters": 4,
"typing_debounce": 800,
},
}
use_service
enables back-end API integration with a deployeddump-things-server
, whentrue
. This option is used throughoutshacl-vue
to enable/disable related UI options (such as theSubmit
button) and for internal request-related functionalityuse-token
allows the use of an authentication token, whentrue
. This enables UI components for the user to enter a token, and adds this token to any requests made to the integrated service.token_info
is instructional text about obtaining a token that will be displayed to a user in the application UItoken_info_url
is a URL that can be added to the instructional text that will be displayed to a user in the application UIservice_base_url
is a list of URLs (minimum 1) of the integrated service. Theurl
property's value should be the actual base URL, and thetype
property's value can be eitherread
orwrite
. This option allows a singleshacl-vue
instance to be integrated with multiple services, for example in curation use cases where user-submitted records should be pushed to awrite
backend, while records that the user should be able to see but not edit will be retrieved from aread
backend.service_endpoints
is a mapping to endpoint templates, for the custom part of the endpoint URL that will be appended to the base URL before a request is made. These templates are typically useful for encoding query parameters. Template variables are included in curly brackets, and current options are{name}
and{curie}
, which follow the same definitions as given above for theclass_name_display
option. Theservice_endpoint
options included in the example below are specific to integration with thedump-things-service
.service_fetch_before
is a list of class URLs indicating from which endpoints records should be fetched upon application startup, i.e. before these classes are actually selected and viewed by the user.service_constrained_search
supportsshacl-vue
's type-ahead search functionality in combination with theget-paginated-records-constrained
service endpoint (see example below). This option is an object with two fields:min_characters
: the minimum number of characters that a user should type before a constrained query is made using theget-paginated-records-constrained
service endpoint; defaults to 4.typing_debounce
: the period (in milliseconds) that qualifies as a pause in typing, triggering the constrained request to be sent; defaults to 800 ms.
URLs should be unique and absolute online URIs.
Example
An example usage of the service_fetch_before
, service_endpoints
, and service_constrained_search
options is given below. Of particular note is the get-paginated-records-constrained
endpoint, which when used for a request will return paginated records for which the JSON-string representation matches the included query parameter. This is used for shacl-vue
's type-ahead search functionality, which is further configurable using the service_constrained_search
option:
{
"service_fetch_before": {
"get-record": [],
"get-records": ["https://concepts.inm7.de/s/flat-base/unreleased/Person"]
},
"service_endpoints": {
"post-record": "record/{name}?format=ttl",
"get-record": "record?pid={curie}&format=ttl",
"get-records": "records/{name}?format=ttl",
"get-paginated-records": "records/p/{name}?format=ttl&size=50&page={page_number}",
"get-paginated-records-constrained": "records/p/{name}?format=ttl&matching=%25{match_string}%25&size=100&page={page_number}"
},
"service_constrained_search": {
"min_characters": 4,
"typing_debounce": 800,
}
}