Skip to content

Creating and Editing Semantic Resources

Jump to bottom
luciaV86 edited this page Feb 1, 2021 · 80 revisions

Creating and Editing Semantic Resource in VocBench

At this moment VocBench EcoPortal is an active service on the EcoPortal platform that allows you to edit and publish specific semantic resources of ecological domain. For this reason the user does not have the possibility to create their own semantic resources without the approval of the administration. The creation of a project in VocBench EcoPortal is the responsibility of the administration which, once the project has been created, assigns the role of Project Manager to the user who has requested it.
To request the creation of a project in VocBench EcoPortal the user has two possibilities:

  • If the user wants to use VocBench EcoPortal for the first time he must register at the following link. When filling in the form, the user, in addition to reporting some personal data, must specify the following fields:
    • Existing semantic resource?: in this field the name and acronym of the semantic resource published in EcoPortal must be reported. E.g. Fish Traits Thesaurus (FISHTRAITS). By default the last submission in EcoPortal is loaded, otherwise specify the version from which to start editing in VocBench. NOTE: to request editing of an EcoPortal semantic resource, you must be the owner of that resource.
    • New semantic resource?: if instead you want to create a new project that will be deployed in EcoPortal, the user must fill in this field by entering the name of the project that will be created by the administrator. E.g. FISHTRAITS. NOTE: in this case it is advisable to specify the name that will be used in EcoPortal as the name of the project.
    • BaseURI: the user fills in this field if he has fill in the "New semantic resource" field as it is necessary to specify it for the creation of a project. If instead the "Existing semantic resource" field has been filled in, the user does not need to specify it.
    • Model: in this field the user enters the model of the new project which can be OWL or SKOS. NOTE: To understand the support of the SKOS model in EcoPortal we recommend reading the following section.
    registration-VocBench-Form
  • If the user is already registered in VocBench EcoPortal and wants to request a new project, it is possible to fill in the form on the HomePage by pressing the "Request Project" button. Projects in VocBench created by the administrator for users have the following default settings:
    createProjectConf
    • Project Name: the name of the project chosen by the user.Any name which can be stored as a folder in the file system is a valid project name. There cannot be projects with the same name.
    • BaseURI: any valid ontology URI is accepted. If the uri ends with no trailing # nor /, the default namespace will end with a #. If the URI ends with /, the default namespace will be the same as the baseuri.
    • Model: it can be RDFS, OWL, SKOS depending on the model (RDFS and OWL for ontologies, SKOS for thesauri)
    • Lexicalization:it can be RDFS, SKOS, SKOS-XL(not supported by EcoPortal) depending on the lexicalization model you want to adopt for your data.
    • History & Validation & Blacklisting: track-change mechanism working at triple-level (see link)
    • Repository Access:
      • CreateRemote:creates a repository on a remote triple store. Currently there are configurable settings for RDF4J and GraphDB stores.
      • Configuration: GraphDB Free is a highly efficient and robust graph database with RDF and SPARQL support.

    To understand in detail the different aspects of the user experience on VocBench, we recommend reading at the following link.

    EcoPortal Deployer for VocBench 3

    • Introduction

      The OntoPortal Deployer is a deployer for VocBench 3 that allows for making semantic resource submissions (specifically OWL ontologies or SKOS thesauri) to OntoPortal catalogs, which are based on the software originally developed for BioPortal and its RESTAPI. The semantic resource being targeted shall already exist on the catalog and be already assigned an acronym, which will be used to identify the semantic resource in the configuration of the deployer. In addition to a configuration for generic BioPortal catalogs, the deployer provides a dedicated configuration for EcoPortal and its new mandatory metadata based on the Data Cite Metadata Schema. The OntoPortal Deployer can be used in an export configuration whose target is a triple store: the OntoPortal Deployer directly consumes the RDF data being exported, without requiring that they are serialized beforehand into a byte sequence conforming to some format. Indeed, the serialization occurs internally as part of the implementation of the submission protocol. This makes a OntoPortal catalogs alike a triple store destination that accepts RDF data, differently from other destinations – say an FTP server – that accept, instead, some byte sequence (and thus require a reformatting exporter to serialize the RDF data). The OntoPortal Deployer was added to VocBench in the release 8.0, while the version discussed in this document will make their way in the upcoming 9.0 release.

    • How to use

      The OntoPortal Deployer can be used when exporting data after selecting the Export Data item under the Global Data Management menu (in the top right corner of the user interface of VocBench 3).

      howtouse.png

      • Basic usage

        The export data panel makes it possible to define complex export configurations. The panel consists of three sections:

        • Graphs to export: this section allows to select which named graphs will be exported. The default selection just contains the graph named after the project base URI, which contains the data being edited.
        • Export transformations: this section allows for configuring a sequence of RDF Transformers, which can be used to manipulate the data being exported (e.g. filter out triples, add triples, replace triples, etc.)
        • Deployment: this section allows to configure the destination of the data being exported and, optionally, transformed. The dropdown menu within the section heading should be used to choose whether the data will be saved to a file, exported to a triple store, or sent to a custom destination. As already discussed, the target of the OntoPortal Deployer is considered a triple store.

        globaldatamanagement.png

        The dropdown list near the Configure button enables to select a different configuration for the OntoPortal Deployer, as depicted in the figure below.

        deployment.png

        Select the item labeled EcoPortal to enable the specific characteristics of the deployer (e.g. additional configuration parameters) dedicated to EcoPortal.

        The warning sign on the right of the widget associated with the OntoPortal Deployer indicates the necessity of further configuration. A click on the Configure button reveals a dialog for editing the chosen configuration. Hereafter, we assume the use of the configuration for EcoPortal, which consists of several fields:

        • API Base URL: The base URL of the OntoPortal REST API. If this parameter is omitted, then the deployer defaults to the official base URL of EcoPortal: http://ecoportal.lifewatchitaly.eu:8080/.
        • API key (mandatory): the API key that will be used to authorize the semantic resource submission. A user’s API key can be found in the user’s account page.
        • Acronym (mandatory): the acronym that identifies the semantic resource for which the submission is being made.
        • Description: a textual description of the semantic resource.
        • Version: the version of the semantic resource.
        • Format (mandatory): the format of the v (either OWL or SKOS).
        • Status (mandatory): the status of the semantic resource (either alpha, beta, production, retired).
        • Release Date (mandatory): the release date of the semantic resource, formatted as yyyy-mm-dd.
        • Contacts (mandatory): at least one contact for the semantic resource. Additional contacts can be added by clicking on the plus button on right. Each contact shall be formatted as name (email), such as Mario Bianchi (mario.bianchi@example.org).
        • Homepage: the address of the main web page of the semantic resource.
        • Documentation: the address of a web page providing documentation for the semantic resource.
        • Publications (mandatory): the address of a web page listing publications for the semantic resource.
        • Creators (mandatory): The main researchers involved in producing the data, or the authors of the publication, in priority order. It is required at least one creator.
        • Titles (mandatory): At least one name or title by which the resource is known.
        • Publisher (mandatory): The name of the entity that holds, archives, publishes prints, distributes, releases, issues, or produces the resource.
        • Publication year (mandatory): The year when the data was or will be made publicly available.
        • Resource type (mandatory): A description of the resource. The format is open, but the preferred format is a single term of some detail.
        • Resource type general(mandatory): The general type of resource.

        ecoportalmetadata.png

        The fields marked with an asterisk (*) are mandatory; all other fields are, instead, optional. Once the deployer has been configured, it is possible to click on the Submit button on the bottom of the Export Data panel to do the actual export, and thus make the semantic resource submission.

      • Data transformation

        The submitted semantic resource must conform to any constraint imposed by EcoPortal. Concerning SKOS, the documentation requires (among other requirements):

        • The use of the property skos:hasTopConcept.
        • The use of plain (no- reified) SKOS labels.

        The first requirement is not met by VocBench by default (since it uses the inverse property skos:isTopConceptOf): however, an RDFTransformer can be used to add the triple expressing the relationship in the opposite direction. The second requirement can be met by using SKOS as lexicalization model. If a project uses SKOS-XL, it can be used a dedicated RDFTrasformer to generate the plain labels from the reified ones.

      • Warning

        The semantic resource submission may not immediately appear on the OntoPortal web application in the list of the semantic resource submissions.

      • Versioning

        Versioning is another item in the Global Data Management menu that allows for saving a snapshot of the data being edited.

        versioning.png

        The suggestion is not to export the CURRENT version that denotes the continually evolving data being edited in a project. Indeed, any submission should be done through the following procedure:

        • create a dump of the data and assign it a version identifier,
        • temporarily switch to the dumped data
        • make the submission using the already described export procedure: the field version in the configuration of the OntoPortal Deployer should match the version identifier of the data dump

    • Test Procedure

      • Test prerequisite

        • A VocBench instance up and running

        • The following steps will be executed by the administrator. Alternatively, the administrator could create the test project and then the project manager could populate it and make the test submission.

        • An account on EcoPortal (the associated API key will be used in the configuration of the OntoPortal Deployer)

        • A private semantic resource that will be the target of the submissions (its acronym will be used in the configuration of the OntoPortal Deployer)

      • Create a test project

        In the Projects tab, click on the Create button.

        createtestproject.png

        In the create project panel, specify the following configuration:

        • Project name: TestThes
        • Base URI: http://example.org/
        • Model: SKOS
        • Lexicalization Model: SKOS

        Leaving the rest of the configuration to the default value, click on the Create button.

        configurationproject.png

        The project should be created in a few instants. Then in the list of projects, there should be a new item for the (empty) project. The open folder indicates that the project is open, but it may be necessary to click on the radio button on the left to access the project.

        openproject.png

        Subsequent steps require moving to the Data tab for editing and then exporting the data.
        In the Scheme tab, click on the create button to create a new skos:ConceptScheme ( []* ):

        schemetab.png

        In the creation dialog, specify as label for the concept scheme being created “continents” in English and then click on the Ok button.

        newconceptscheme.png

        Then select the newly created scheme:

        selectconceptscheme

        In the Concept tab, click on the create button to create a new skos:Concept ( ()* ):

        concepttab.png

        In the creation dialog, specify as label for the concept being created “Africa” in English and then click on the Ok button.

        createconcept.png

        Do the same to create the following concepts:

        • America
        • Asia
        • Europe
        • Oceania

        At the end, the concept tree should contain a flat list of the five continents.

        listconcept.png

      • Export data

        Under the Global Data Menu (top right corner of the user interface), select the menu item Export Data.

        In the Export Data panel, select as deployment option Deploy to a triple store and then the OntoPortal Deployer, using the EcoPortal configuration.

        testdeployment.png

        Configure the OntoPortal Deployer with the following parameters:

        • API Base URL: default if selected as OntoPortal Deploy - EcoPortal: http://ecoportal.lifewatchitaly.eu:8080/
        • API key (mandatory): your API key
        • Acronym (mandatory): the acronym of your ontology on EcoPortal (E.g.: FISHTRAITS)
        • Description: A test thesaurus to experiment with EcoPortal
        • Version: (recommended E.g.: 202017 - yyyymmdd)
        • Format (mandatory): SKOS
        • Status (mandatory): alpha
        • Release Date (mandatory): 2020-11-16 (yyyy-mm-dd).
        • Contacts (mandatory):
        • Homepage: http://example.org/testhes/homepage
        • Documentation: http://example.org/testhes/documentation
        • Publications (mandatory): http://example.org/testhes/publications
        • Creators (mandatory):
          • Mario Bianchi
          • Mario Rossi
        • Titles (mandatory):
          • Title: Test thesaurus
            Language: en-US (the language can be edited by clicking on the flag icon near each title)
            Title type: Other
          • Title: Tesauro di prova
            Language: it
            Title type: TranslatedTitle
        • Publisher (mandatory): LifeWatch ERIC
        • Publication year (mandatory): 2020
        • Resource type (mandatory): Thesaurus
        • Resource type general(mandatory): Other

        testecoportalmetadata.png

        The language tag of the titles can be chosen from a dialog containing the system languages:

        valuelanguage.png

        The field Resource type is an open enumeration, in the sense that the system provides a few suggested values, while the user is free to enter whatever string. The suggestions are shown inside a dropdown (or drop-up) list when types. Depending on the browser its possible to open this list without typing:

        • By double clicking on the field in Firefox
        • With a single click on the field in Chrome

        The submitted SKOS data must use the property skos:hasTopConcept to relate a concept scheme to the roots of the concept tree. Unfortunately, VocBench 3 only uses its inverse property (skos:topConceptOf) to relate a concept to the schemes of which it is a top concept thereof.

        It is possible to circumvent this problem by adding and RDFTransformer that generates the inverse triple on the fly during the export procedure. On the section Export transformations, click on the plus button and then select the SPARQL RDF Transformer.

        exporttransformation.png

        Click on the Configure button and specify the following filter in the configuration dialog:

        INSERT {
        ?s <http://www.w3.org/2004/02/skos/core#hasTopConcept> ?c
        }WHERE {
        ?c <http://www.w3.org/2004/02/skos/core#topConceptOf> ?s
        }

        configurationSPRQLupdate.png

        (note that the filter field can be enlarged by dragging the grabber on the bottom right corner of the text area). Click on the Submit button on the bottom of the Export Data panel to create the submission to EcoPortal. After a while you should receive a confirmation message.

        exportdata.png

      • Verification

        Log in into EcoPortal and open the page of your target semantic resource.

        verification.png

        Submissions are handled asynchronously: at first, we might see that the submission is just Uploaded, but subsequently we should see that it is marked with Parsed, Indexed, Metrics and Annotator.

        In some circumstances, the new submission may not be visible at all just inside the web page. In this case, we can verify that EcoPortal has received the submission by fetching the submissions using the REST API.

        To do so it is possible to several tools, including the Postman app.

        Click on the plus button in the tab set on the right of the window to open a new tab for the request.

        postmanrequest.png

        In the text field on the top write the following address: http://ecoportal.lifewatchitaly.eu:8080/ontologies/TESTTHES/submissions (replace the ontology acronym – TESTTHES – with your own - ontologies/ACRONYM/submissions)

        Then click on the inner tab labelled Headers, and add a header:

        • Key: Authorization
        • Value: apikey token=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxx

        Where the part underlined in green should be replaced with your own API key (the same used inside VocBench). Then press the Send button, to do the actual request.
        In the retuned JSON response, you should find an object describing the submission just done (note the name and email of the contacts).

        postmanresponse.png

        The contacts are returned in an arbitrary order, which may not match the one used in the original request.

    SKOS Support

    • Support for SKOS vocabularies in EcoPortal

      EcoPortal is a web-based portal for accessing and sharing semantic resources. The application accepts semantic resource submissions in OWL and OBO format, and SKOS vocabularies that contain particular constructs. This wiki page documents the minimum set of SKOS constructs that must be present in a SKOS vocabulary for EcoPortal to accept and handle the submission properly. Please note that the SKOS constructs described here are handled only for vocabularies that are identified as SKOS when they are submitted to EcooPortal. Vocabularies submitted as OWL or OBO formats are not examined for SKOS constructs.

      • Required SKOS constructs

        • skos:Concept: Concepts are the fundamental elements of SKOS vocabularies and are asserted using the skos:Concept class, e.g.:

          <http://www.example.com/animals> rdf:type skos:Concept

          In SKOS vocabularies, EcoPortal only treats the SKOS concept assertions as concepts to be displayed. If the vocabulary contains other assertions about other types of concepts, EcoPortal will not treat these as concepts in any of its displays or features.

          See the W3C's SKOS System Primer and SKOS Reference for concept documentation and examples:

          Note:

          Some OWL ontologies declare the SKOS namespace to facilitate minimal use of SKOS constructs for things like labels (e.g., skos:prefLabel, skos:altLabel) or mappings (e.g., skos:exactMatch, skos:broaderMatch). In these cases, the proper format for new ontology submissions is OWL, not SKOS.

        • skos:ConceptScheme & skos:hasTopConcept: For every semantic resource entry in EcoPortal, the application provides a tabbed interface with various views of the semantic resource data, e.g., a "Classes" tab with a tree structure to graphically depict the hierarchical collection of semantic resource classes.

          In the case of SKOS vocabularies, EcoPortal determines which concepts to display as roots in the concept tree by querying vocabulary content for occurrences of skos:hasTopConcept property assertions. Top concepts are the most general concepts contained in SKOS concept schemes (an aggregation of one or more SKOS concepts).

          The following example, taken from the SKOS System Primer, shows how to define a concept scheme and link it to the most general concepts it contains:

          @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
          @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
          @prefix ex: <http://www.example.com/> .

          ex:animalThesaurus rdf:type skos:ConceptScheme;
          skos:hasTopConcept ex:mammals;
          skos:hasTopConcept ex:fish.

          SKOS vocabularies submitted to EcoPortal must contain a minimum of one concept scheme and top concept assertion. See the the SKOS System Primer and SKOS Reference for more documentation of concept schemes and top concepts:

          If your vocabulary declares more than one concept scheme, all of the top concepts will be aggregated and displayed as root level concepts. EcoPortal's user interface doesn't provide support for grouping top level concepts by concept scheme. It is recommended to declare a owl:Ontology, especially for metadata annotations.

      • Hierarchy in SKOS vocabularies

        The only semantic relationship in SKOS vocabularies that EcoPortal uses to construct and display concept hierarchies is the skos:broader property.

        ex:mammals rdf:type skos:Concept;
        skos:prefLabel "mammals"@en;
        skos:broader ex:animals.

        Other properties used to denote hierarchical relationships like skos:narrower, skos:broaderTransitive, and skos:narrowerTranstive, are ignored.

      • Metrics data for SKOS vocabularies

        EcoPortal uses the OWL API for parsing all ontology and vocabulary submissions, as well as for the calculation of metrics data. The OWL API treats SKOS vocabularies as RDF files containing classes and instances. According to the SKOS Reference, concepts are instances of owl:Class, and thus are counted as instances (a.k.a. "individuals").

        When viewing metrics tables in the EcoPortal user interface, the value for the "NUMBER OF INDIVIDUALS" corresponds to the number of concepts in any given SKOS vocabulary.

        metrics_Fish_Traits_thesaurus in EcoPortal

      • SKOS-XL

        Currently EcoPortal offers no support for the SKOS eXtension for Labels (SKOS-XL). A suggested workaround for SKOS vocabularies that make use of SKOS-XL, is to dump the value of labels (i.e., skosxl:literalForm of skosxl:*Label instances) into the corresponding skos:*Label property.

      • SKOS mapping properties

        At this time, EcoPortal doesn't use SKOS mapping properties, i.e., skos:*Match, to populate the mapping repository. One-to-one mappings between SKOS concepts need to be uploaded separately via the EcoPortal REST API.

    • Example of valid SKOS

      This example provides a simple illustration of the composition of a SKOS file that complies with the above constraints.

      • Example header

        The header shown here defines a few typical namespaces that may be useful.
        The last namespace is the one that defines this SKOS vocabulary. Ideally, the IRI defining the myskosid namespace is the resolvable location of the SKOS ontology.

        
   <xml version="1.0" encoding="UTF-8"?>
   <rdf:RDF
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
     xmlns:skos="http://www.w3.org/2004/02/skos/core#"
     xmlns:dct="http://purl.org/dc/terms/"
     xmlns:myskosid="https://example.org/ontologies/myskosontology/"
   >

      • Example semantic resource description

        In the rdf:type item, this namespace is declared as the ConceptScheme. The ConceptScheme does not have to be the same as the namespace of the ontology.

        Other metadata is provided as an example of good practices in ontology metadata. The dct:creator does not have to be an ORCID ID, but a unique identifier is an ideal way of naming a creator (whether individual or organization).

        This semantic resource has only 2 concepts (to be defined below), hence only 2 skos:hasTopConcept declarations.

        
   <rdf:Description rdf:about="https://example.org/ontologies/myskosontology/">
     <rdfs:label xml:lang="en">Example SKOS ontology for EcoPortal</rdfs:label>
     <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#ConceptScheme"/>
     <rdfs:comment xml:lang="en">Example created to simplify understanding and creation of a SKOS vocab for EcoPortal</rdfs:comment>
     <dct:created rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2020-09-16</dct:created>
     <dct:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2020-09-16</dct:modified>
     <dct:license rdf:resource="https://creativecommons.org/licenses/by/4.0/"/>
     <dct:creator rdf:resource="https://orcid.org/0000-0001-6875-5360"/>
     <skos:hasTopConcept rdf:resource="https://example.org/ontologies/myskosontology/fragmentid001"/>
     <skos:hasTopConcept rdf:resource="https://example.org/ontologies/myskosontology/fragmentid002"/>
   </rdf:Description>

      • Example term definitions

        This section shows the two concepts and a few typical annotations about those concepts. The first rdf:Description line of each group names the concept that is being defined in the indented lines following.

        The rdf:Type and skos:prefLabel are required annotation content for EcoPortal to work effectively. Other items are optional.

        The skos:topConceptOf is not strictly required for EcoPortal SKOS semantic resources, but provides useful contextualization if there is more than one topConcept.

        
   <rdf:Description rdf:about="https://example.org/ontologies/myskosontology/fragmentid001"">
     <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/>
     <skos:prefLabel xml:lang="en">First concept</skos:prefLabel>
     <skos:definition xml:lang="en">The very first example provided as part of this semantic resource.</skos:definition>
     <skos:topConceptOf rdf:resource="https://example.org/ontologies/myskosontology/"/>
   </rdf:Description>
   <rdf:Description rdf:about="https://example.org/ontologies/myskosontology/fragmentid002"">
     <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/>
     <skos:prefLabel xml:lang="en">Second concept</skos:prefLabel>
     <skos:definition xml:lang="en">The very first example provided as part of this semantic resource.</skos:definition>
     <skos:topConceptOf rdf:resource="https://example.org/ontologies/myskosontology/"/>
   </rdf:Description>

      • Closing XML

        Needed for a complete, parseable RDF file!

        </rdf:RDF>

    Copyright © 2021, LifeWatch ERIC. All rights reserved.

    EcoPortal

    Clone this wiki locally