Repository hosting public material and documentation for the Reference Data Service (RDS), a project of the University of Zürich provided by the Swiss Art Research Infrastructure (SARI) and powered by metaphacts.
The Reference Data Service (the so-called RDS-Global system) provides access to datasets like AAT, ULAN, GeoNames, Wikidata, GND EntityFacts, and a few more.
You can also launch your own local service which fetches data from the upstream RDS-Global system.
First of all you should ensure that docker and docker-compose are installed on your computer. Once this step is done, you can move to the second one.
- clone or download this repository
- In your local copy, navigate to the
docker-composefolder and execute the following command:docker-compose up -d. This command will start the platform in a few minutes. - Once the system is running you can access the platform using the url: http://localhost:8080 or https://localhost:8443.
- The default credentials are username
adminand passwordadmin. This can be changed by going to the settings menu (gear icon on the top-right) and from there to Security
Some additional configuration is recommended in order to use the full functionality of the platform. Example configurations are provided as .ttl and .trig files in the /configuration folder.
- Log in as Administrator and navigate to the Administration page by clicking on the cog wheel in the top right of the menu bar
- Click on Data Import & Export
- Upload the
dataset-metadata.ttlfile using the File Upload interface- This will display additional information when searching through external datasets
- Click on Advanced Options and enter the following URI in the field URI of the target NamedGraph:
http://schema.swissartresearch.net/rds/type-mapping. Then upload thetype-mapping.ttlfile through the File Upload interface- This will ensure the correct data types are used when searching for existing and newly created records
If you intend to use your RDS-Local instance for data creation, perform the following steps.
- Navigate to the Administration page and access the Security configuration.
- For editing records a user needs to have the
rds-editorrole. Click on theadminuser to assign the role to this user. - The form under the list will change to Update Account. Add the
rds-editorto the list of roles and click Update. - Add the
rds-editorto any user that requires editing rights. - Return to the Administration page and navigate to the Data Import & Export page.
- Upload the
user-roles.ttlfile.- This defines the roles of individual users in the editing workflow.
- To stop the platform you can execute the
docker-compose stopcommand. - After changing any container configuration the platform needs to be re-created using
docker-compose up -dagain. - The container configuration can be customized (injection of volumes, memory settings, ...) in the file
docker-compose.override.yml. Please do not touchdocker-compose.yml, rather copy sections todocker-compose.override.ymland change them there - The logs are available using
docker-compose logs -f
The RDS lookup service follow the Reconciliation API developed by the W3C "Working Group Reconciliation Service API". Full specs of the API can be found here
- https://reconciliation-api.github.io/specs/latest/
- https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API While a live test bench for the API is available at the address below
- https://reconciliation-api.github.io/testbench/
The current implementation of the Reconciliation API only includes a reconciliation service (Look-up service). Only the following rest endpoints are available:
GET /rest/reconciliation (without any parameters) - returns manifest of the service in JSON(P) format (Depending on Accept field in the header).
GET /rest/reconciliation?query={JSON_QUERY} - where JSON_QUERY is a url-encoded query-json-object
And response is a list of reconciliation candidates described in the documentation: For multiple queries, the response is a JSON literal object with the same keys as in the request
{
"q0" : {
"result" : { ... }
},
"q1" : {
"result" : { ... }
}
}
Each result consists of a JSON literal object with the structure
{
"result" : [
{
"id" : ... string, database ID ...
"name" : ... string ...
"type" : ... array of strings ...
"score" : ... double ...
"match" : ... boolean, true if the service is quite confident about the match ...
},
... more results ...
],
... potentially some useful envelope data, such as timing stats ...
}
The results should be sorted by decreasing score. The service must also support JSONP through a callback parameter ie &callback=foo. POST /rest/reconciliation - support similar (to previous endpoint) functionality, the only difference is that JSON_QUERY is provided as JSON-object in the body of POST-request.
- To get manifest use:
curl --location --request GET 'https://rds.swissartresearch.net/rest/reconciliation' --header 'Content-Type: application/json' --header 'Accept: application/json'- To get response via GET use:
curl --location --request GET 'https://rds.swissartresearch.net/rest/reconciliation?queries=%7B%22q0%22%3A%7B%22query%22%3A%22Meinheim%22%2C%22type%22%3A%22http%3A%2F%2Fwww.w3.org%2F2004%2F02%2Fskos%2Fcore%23OrderedCollection%22}}&callback=alert' - To get response via POST(raw-json) use:
curl --location --request POST 'https://rds.swissartresearch.net/rest/reconciliation' --header 'Content-Type: application/json' --header 'Accept: application/json' --data-raw '{"q2":{"query":"Car","limit":3},"q3":{"query":"Home","limit":3},"q0":{"query":"Meinheim","limit":3}}'- To get response via POST(form) use:
curl --location --request POST 'https://rds.swissartresearch.net/rest/reconciliation' --header 'Content-Type: application/json' --header 'Accept: application/json' --form 'queries={"q2":{"query":"Car","limit":3},"q3":{"query":"Home","limit":3},"q0":{"query":"Meinheim","limit":3}}'- To get response via POST(url-encoded form) use:
curl --location --request POST 'https://rds.swissartresearch.net/rest/reconciliation' --header 'Content-Type: application/json' --header 'Accept: application/json' --data-urlencode 'queries={"q2":{"query":"Car","limit":3},"q3":{"query":"Home","limit":3},"q0":{"query":"Meinheim","limit":3}}'Label service is a central service of the platform which maps labels to resources by their iris. (This service can be configured using preferredLabels configuration in the UI props)
To get labels for your resources use following endpoint:
POST: {RDS-L/RDS-G}/rest/data/rdf/utils/getLabelsForRdfValue - where the set of resource IRIs should be provide as JSON-array in the body of the POST request.
Example:
curl --location --request POST 'https://rds-mph.swissartresearch.net/rest/data/rdf/utils/getDescriptionForRdfValue' -
-header 'Accept: application/json' --header 'Content-Type: application/json' --data-raw '["http://example.com/resource-iri"]'
Description service is very similar to the label service. It maps descriptions to resources by their iris. (This service can be configured using preferredDescription configuration in the UI props)
To get descriptions for your resources use following endpoint:
POST: {RDS-L/RDS-G}/rest/data/rdf/utils/getDescriptionForRdfValue - where the set of resource IRIs should be provide as array in the body of POST request.
Example:
curl --location --request POST 'https://rds-global.swissartresearch.net:443/rest/data/rdf/utils/getDescriptionForRdfValue' --header 'Content-Type: application/json' --data-raw '["http://example.com/resource-iri"]'