Skip to content

Latest commit

 

History

History
447 lines (407 loc) · 32.7 KB

guide.md

File metadata and controls

447 lines (407 loc) · 32.7 KB

Metadata usage in WIDOCO

There are two ways to make WIDOCO aware of the metadata of your ontology:

  • Add metadata annotations in your ontology. This makes ontology maintenance easier when you publish new versions, as metadata is included in the ontology. In our best practice document we show which properties you should add in your ontology for this purpose. This is the recommended option.
  • Declare a .properties file: A collection of key-value pairs where all the metadata is specified. Since it's a specific file, it has to be maintained separately from the ontology.

In this document we illustrate how Widoco uses metadata in the final documentation of your ontology, using both options specified above.

Namespaces used in this document

Namespace prefix URI
bibo http://purl.org/ontology/bibo/
cc http://creativecommons.org/ns#
dc http://purl.org/dc/elements/1.1/
dcterms http://purl.org/dc/terms/
doap http://usefulinc.com/ns/doap#
foaf http://xmlns.com/foaf/0.1/
mod https://w3id.org/mod#
obo http://purl.obolibrary.org/obo/
org http://www.w3.org/ns/org#
owl http://www.w3.org/2002/07/owl#
pav http://purl.org/pav/
prov http://www.w3.org/ns/prov#
rdfs http://www.w3.org/2000/01/rdf-schema#
schema https://schema.org/
sw http://www.w3.org/2003/06/sw-vocab-status/ns#
skos http://www.w3.org/2004/02/skos/core#
vaem http://www.linkedmodel.org/schema/vaem#
vann http://purl.org/vocab/vann/
vcard http://www.w3.org/2006/vcard/ns#
wdrs http://www.w3.org/2007/05/powder-s#
widoco https://w3id.org/widoco/vocab#

Metadata usage in WIDOCO

This section explains the metadata recognized by WIDOCO for both ontology annotations and term annotations.

Vocabulary annotations

The table below shows which ontology metadata annotations are recognized in WIDOCO in alphabetical order:

Metadata category Ontology annotation property* config.properties field(s)** Good practices document Accepted property value Example
Abstract dc:abstract, dcterms:abstract abstract Sec 3.2.4 [OPTIONAL] Text ontology, config
Backwards compatible owl:backwardCompatibleWith backwardCompatibleWith Sec 3.3.3 [OPTIONAL] URI ontology, config
Bibliographic citation dcterms:bibliographicCitation, schema:citation citeAs Sec 3.6.2 [OPTIONAL] Text ontology, config
Code repository schema:codeRepository, doap:repository codeRepository Sec 3.10 [OPTIONAL] URI ontology, config
Contributors dcterms:contributor, dc:contributor, schema:contributor, pav:contributedBy, doap:documenter, doap:maintainer, doap:helper, doap:translator contributors, contributorsURI, contributorsInstitution, contributorsInstitutionURI Sec 3.5.2 [RECOMMENDED] Text or Person or BNode ontology, config
Creation date dcterms:created, schema:dateCreated, prov:generatedAtTime, pav:createdOn, doap:created dateCreated Sec 3.4.2 [OPTIONAL] Text ontology, config
Creators dcterms:creator, dc:creator, schema:creator, pav:createdBy, pav:authoredBy, prov:wasAttributedTo, doap:developer, foaf:maker authors, authorsURI, authorsInstitution, authorsInstitutionURI Sec 3.5.1 [RECOMMENDED] Text or Person or BNode ontology, config
Description dc:description, dcterms:description, schema:description, rdfs:comment, skos:note, doap:description, doap:shortdesc description Sec 3.2.3 [OPTIONAL] Text ontology, config
Diagram foaf:image, foaf:depiction, schema:image diagram Sec 3.8.2 [OPTIONAL] Text ontology, config
DOI bibo:doi DOI Sec 3.6.1 [OPTIONAL] Text ontology, config
Extended ontologies voaf:extends extendedOntologyNames, extendedOntologyURIs Sec 3.4.6 [OPTIONAL] URI ontology, config
Funders (org, person) foaf:fundedBy schema:funder funders Sec 3.5.4 [OPTIONAL] Text or URI ontology, config
Funding grants schema:funding fundingGrant Sec 3.5.5 [OPTIONAL] Text or URI ontology, config
Incompatible with owl:incompatibleWith incompatibleWith Sec 3.3.4 [OPTIONAL] URI ontology, config
Imported ontologies owl:imports importedOntologyNames, importedOntologyURIs N/A [RECOMMENDED] (good practice in ontology engineering) URI ontology, config
Issued date dcterms:issued, schema:dateIssued dateIssued Sec 3.4.4 [OPTIONAL] Text ontology, config
License dc:rights, dcterms:license, schema:license, cc:license, doap:license licenseName, licenseURI, licenseIconURL Sec 3.7 [OPTIONAL] Text or URI ontology, config
Logo foaf:logo, schema:logo logo Sec 3.8.1 [OPTIONAL] URI ontology, config
Name rdfs:label, mod:acronym, schema:alternateName, skos:prefLabel ontologyName Sec 3.2.1 [RECOMMENDED] Text ontology, config
Namespace prefix vann:preferredNamespacePrefix ontologyPrefix Sec 3.1.2 [RECOMMENDED] Text ontology, config
Namespace URI vann:preferredNamespaceUri ontologyNamespaceURI Sec 3.1.1 [RECOMMENDED] URI ontology, config
Modification date dcterms:modified, schema:dateModified pav:lastUpdatedOn dateModified Sec 3.4.3 [OPTIONAL] Text ontology, config
Previous version dc:replaces, dcterms:replaces, prov:wasRevisionOf, pav:previousVersion, owl:priorVersion previousVersionURI Sec 3.4.1 [RECOMMENDED] URI ontology, config
Publisher dcterms:publisher, dc:publisher, schema:publisher publisher, publisherURI, publisherInstitution, publisherInstitutionURI Sec 3.5.3 [OPTIONAL] Text or Organization or BNode ontology, config
Similar resources rdfs:seeAlso Sec 3.9 [OPTIONAL] Text ontology, config
Status bibo:status mod:status schema:creativeWorkStatus status Sec 3.2.4 [OPTIONAL] Text or Status ontology, config
Source dc:source, dcterms:source, prov:hadPrimarySource, wdrs:describedBy source Sec 3.4.5 [OPTIONAL] URI ontology, config
Title dc:title, dcterms:title, schema:name ontologyTitle Sec 3.2.2 [RECOMMENDED] Text ontology, config
Version IRI owl:versionIRI thisVersionURI Sec 3.3.1 [RECOMMENDED] URI ontology, config
Version number owl:versionInfo, schema:schemaVersion, pav:version, dcterms:hasVersion ontologyRevisionNumber Sec 3.3.2 [RECOMMENDED] Text ontology, config

* All listed properties are supported by WIDOCO.

** Configuration properties do not support URIs or blank nodes. Hence, additional properties are needed (like authorsURI, contributorsURI) to annotate URIs in case they are needed.

Custom annotations

We prioritize reusing metadata properties defined already. However, a small subset of OPTIONAL annotation properties (i.e., introduction and the URL to the different serializations) have been introduced by WIDOCO to customize parts of the documentation from the ontology itself:

Metadata category Ontology annotation property* config.properties field(s)** Good practices document Accepted property value Example
Introduction widoco:introduction introduction N/A [OPTIONAL] Text ontology, config
N-Triples serialization widoco:ntSerialization NTSerialization N/A [OPTIONAL] [URL] ontology, config
JSON-LD serialization widoco:jsonldSerialization JSONLDSerialization N/A [OPTIONAL] [URL] ontology, config
RDF-XML serialization widoco:rdfxmlSerialization RDFXMLSerialization N/A [OPTIONAL] [URL] ontology, config
Turtle serialization widoco:turtleSerialization TurtleSerialization N/A [OPTIONAL] [URL] ontology, config

Term (classes, properties and data properties) annotations

The table below summarizes all the metadata annotations recognized for ontology terms, in alphabetical order. Note that there are no config.properties annotations here, as these annotations are only read from the ontology file.

Metadata category Ontology annotation property Good practices document Accepted property value Example
Definition rdfs:comment, skos:definition Sec 4.2 [RECOMMENDED] Text ontology
Deprecation status owl:deprecated Sec 4.5.1 [OPTIONAL] Boolean ontology
Editorial note skos:editorialNote N/A [OPTIONAL] Text ontology
Example vann:example, skos:example Sec 4.4 [OPTIONAL] Text ontology
Label rdfs:label, skos:prefLabel, obo:IAO_0000118 Sec 4.1 [RECOMMENDED] Text ontology
Original source rdfs:isDefinedBy, dc:source Sec 4.3 [OPTIONAL] URI ontology
Rationale vaem:rationale Sec 4.6 [OPTIONAL] Text ontology
Status sw:term_status, obo:IAO_0000114 Sec 4.5.2 [OPTIONAL] Text ontology

Example: Using ontology annotations (Back to table)

The following Turtle code block shows sample annotations for each of the metadata categories on an ontology with namespace URI https://w3id.org/example:

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix dc: <http://purl.org/dc/elements/1.1/> .
@prefix schema: <https://schema.org/> .
@prefix voaf: <http://purl.org/vocommons/voaf#> .
@prefix vann: <http://purl.org/vocab/vann/> .
@prefix widoco: <https://w3id.org/widoco/vocab#> .
@prefix bibo: <http://purl.org/ontology/bibo/> .

<https://w3id.org/example> rdf:type owl:Ontology ;
    owl:versionIRI <https://w3id.org/example/1.0.1> ;
    dcterms:abstract "An example vocabulary designed to illustrate how to publish vocabularies on the Web following the FAIR principles"@en ;
    dc:description "This is an example ontology to illustrate some of the annotations that should be included"@en ;
    dc:title "The example ontology"@en ;
    dcterms:created "February 5th, 2020"@en ;
    dcterms:creator "Daniel Garijo"@en ,"Maria Poveda-Villalon"@en ;
    dcterms:license <http://creativecommons.org/licenses/by/2.0/> ;
    vann:preferredNamespacePrefix "exo"@en ;
    vann:preferredNamespaceUri "https://w3id.org/example" ;
    schema:citation "Cite this vocabulary as: Garijo, D. and Poveda-Villalón, M. The example ontology 1.0.1."@en ;
    rdfs:comment "An example vocabulary designed to illustrate how to publish vocabularies on the Web following the FAIR principles. This vocabulary describes three simple classes with 3 properties and a data property."@en ;
    rdfs:label "Example" ;
    owl:backwardCompatibleWith <https://w3id.org/example/1.0.0> ;
    owl:priorVersion <https://w3id.org/example/1.0.0> ;
    voaf:extends <https://w3id.org/otherOntology> ;
    owl:imports <http://www.w3.org/2000/01/rdf-schema> ;
    bibo:status <http://purl.org/ontology/bibo/status/draft> ;
    foaf:fundedBy <https://example.org/fundingOrganization> ;
    schema:funding <https://example.org/fundingGrant> ;
    schema:codeRepository "https://github.com/dgarijo/example"^^xsd:anyURI;
    widoco:introduction "A paragraph with the introduction section of the documentation about your resource"@en ;
    widoco:rdfxmlSerialization "https://example.org/serialization/ontology.xml"^^xsd:anyURI ; 
    owl:versionInfo "1.0.1" .
    #If content negotiation is enabled, the widoco:rdfxmlSerialization annotation may not be needed.

Annotating the ontology using entities:

Certain categories like Authors, Contributors and Publisher can be annotated as RDF entities. If a URI or a blank node are used in these categories, Widoco will look for the the resource within the ontology itself (resolving external URIs is not currently supported). An example using a URI and a blank node can be seen below:

If URIs are used to define the creators of an ontology, the result would be similar to the snippet below:

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix schema: <https://schema.org/> .

<https://w3id.org/example> rdf:type owl:Ontology ;
    schema:creator <https://w3id.org/example/ind/dgarijo> ,<https://w3id.org/example/ind/mpoveda> .

If blank nodes are used, then the the result should look similar to the following snippet:

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix schema: <https://schema.org/> .

<https://w3id.org/example> rdf:type owl:Ontology ;
    schema:creator [
        a schema:Person;
        schema:name "Daniel Garijo"
    ] ,[
        a schema:Person;
        schema:name "María Poveda"
    ] .

Widoco will recognize the following properties when describing agents (persons or organizations):

Metadata category Ontology annotation property Accepted property value
Affiliation schema:affiliation, org:memberOf Text or Organization or BNode
Family Name schema:familyName, vcard:family-name, foaf:family_name Text
Full name rdfs:label, schema:name, vcard:fn, foaf:name Text
Given name schema:givenName, vcard:given-name, foaf:givenname Text
Email schema:email, vcard:hasEmail, foaf:mbox Text
URL schema:url, vcard:hasURL, foaf:homepage URI

Annotating ontology terms:

For status, the known values are: unstable, testing, stable and archaic

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vann: <http://purl.org/vocab/vann/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix sw: <http://www.w3.org/2003/06/sw-vocab-status/ns#> .
@prefix : <https://w3id.org/example#> .

:Researcher rdf:type owl:Class ;
            vann:example "Daniel Garijo."@en ;
            vaem:rationale "The concept Researcher was added to the ontology to represent those authors of scientific publications that belong to a public institution."@en ;
            rdfs:comment "A researcher is a person who publishes scientific papers, writes research proposals and mentors students"@en ;
            sw:status "unstable";
            rdfs:isDefinedBy <https://w3id.org/example#> ;
            skos:editorialNote "Some editorial note by the creator of the term" ;
            rdfs:label "Researcher"@en .

Example: Using a configuration file (Back to table)

Create a config.properties file and use the -confFile option to invoke Widoco. The metadata is declared with a key=value pair as shown below:

abstract=An example ontology
authors=First Author;Second Author
authorsURI=http://example.org/author1;http://example.org/author2
authorsInstitution=First author institution;Second author institution
authorsInstitutionURI=https://www.isi.edu/;https://www.isi.edu/
backwardCompatibleWith=https://w3id.org/example/1.0.0
citeAs="add some citattion text here."
codeRepository=https://github.com/dgarijo/example
contributors=First contributor;Second contributor
contributorsURI=http://example.org/contributor1;http://example.org/contributor2
contributorsInstitution=First contributor institution;Second contributor institution
contributorsInstitutionURI=https://isi.edu/;https://isi.edu/
dateCreated="13 Nov, 2022"
dateIssued="14 Nov, 2022"
dateModified="15 April, 2023"
description=A description of what the ontology does goes here
extendedOntologyNames=test1; test2
extendedOntologyURIs=http://example.org/test1; http://example.org/test2
DOI=https://dx.doi.org/SOME/DOI
funder=https://example.org/institution
funding=https://example.org/fundingGrant
incompatibleWith=https://w3id.org/example/0.0.1
images=image1.png;image2.png
importedOntologyNames=Imported Ontology 1; Imported Ontology 2
importedOntologyURIs=http://example.org/test11; http://example.org/test22
introduction=A brief text for the introduction section may be written here.
licenseURI=http://creativecommons.org/licenses/by/2.0/
licenseName=CC-BY
licenseIconURL=https://i.creativecommons.org/l/by/2.0/88x31.png
logo="https://example.org/logo.svg"
ontologyName=The Cohort Ontology
ontologyNamespaceURI=https://w3id.org/example
ontologyTitle=The Example Ontology
ontologyPrefix=exo
ontologyRevisionNumber=1.0.0
pathToAbstract=abstract.html (superseedes abstract)
pathToDescription=description.html (superseedes description)
pathToIntro=intro.html (supersedes introduction)
pathToOverview=overview.html
pathToReferences=references.html
previousVersionURI=https://w3id.org/example/1.0.0
publisher=Ontology Engineering Group
publisherURI=https://oeg-upm.es
publisherInstitution=UPM
publisherInstitutionURI=https://www.upm.es
thisVersionURI=https://w3id.org/example/1.0.1
source=http://source1;http://source2
seeAlso=http://firstResource
status=Ontology Specification Draft
JSONLDSerialization=ontology.nt
NTSerialization=ontology.nt
RDFXMLSerialization=ontology.xml
TurtleSerialization=ontology.ttl

Glossary (Back to table)

Text: A literal written in a textual manner.

URI: A URL that describes the target resource.

Boolean: True or False.

Status: Status of a term, or the ontology document. For terms, known statuses are: unstable, testing, stable and archaic (see the W3C sw-vocab for reference).

Person: Entity used to refer to people in general.

Organization: Entity used to represent an insitution or company. Typically used as the range of the publisher metadata property.

BNode: Blank node, used to refer to an entity without assigning an URI to that entity.