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
.propertiesfile: 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.
This section explains the metadata recognized by WIDOCO for both ontology annotations and term annotations.
The table below shows which ontology metadata annotations are recognized in WIDOCO in alphabetical order:
* 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.
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 |
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.
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 |
| schema:email, vcard:hasEmail, foaf:mbox | Text | |
| URL | schema:url, vcard:hasURL, foaf:homepage | URI |
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.