Skip to content

Commit

Permalink
fix #610, fix #602, fix #605, Fix #544, Fix #612
Browse files Browse the repository at this point in the history
  • Loading branch information
@dgarijo
dgarijo committed Aug 25, 2023
1 parent aa9a385 commit f1fa7b4
Show file tree
Hide file tree
Showing 23 changed files with 494 additions and 172 deletions.
42 changes: 41 additions & 1 deletion doc/bestPractices/sections/checklist-en.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,9 @@ <h4 class="list" id="status">Status [<em class="rfc2119" title="OPTIONAL">OPTION
<ul class="hlist"><strong>Properties you may use</strong>:
<li><a target="_blank" href="http://purl.org/ontology/bibo/status">bibo:status</a> <strong>(PREFERRED)</strong></li>
<li><a target="_blank" href="https://w3id.org/mod#status">mod:status</a></li>
<li><a target="_blank" href="https://schema.org/creativeWorkStatus">schema:creativeWorkStatus</a></li>
</ul>
Note that the range of bibo:status is a "bibo:DocumentStatus" instance. Common status include: bibo:status/accepted, bibo:status/draft, bibo:status/published, bibo:status/rejected and bibo:status/peerReviewed. For more information, please see the <a href="http://purl.org/ontology/bibo/">bibo vocabulary</a>. In MOD, the status is a string.
Note that the range of bibo:status is a "bibo:DocumentStatus" instance. Common status include: bibo:status/accepted, bibo:status/draft, bibo:status/published, bibo:status/rejected and bibo:status/peerReviewed. For more information, please see the <a href="http://purl.org/ontology/bibo/">bibo vocabulary</a>. In MOD, status is a string. In schema.org, status may refer to a string or to a <a href="https://schema.org/DefinedTerm">schema:DefinedTerm</a>.

<h5>Example:</h5>
<pre>
Expand Down Expand Up @@ -433,6 +434,45 @@ <h5>Example:</h5>
dct:publisher &lt;http://www.oeg-upm.net/; .
</pre>

<h4 class="list" id="funder">Funder [<em class="rfc2119" title="OPTIONAL">OPTIONAL</em>]</h4>
<p>
Organizations (or persons) responsible for funding the vocabulary. Ontologies are often a product of funding organizations, and hence they should be acknowledged.
</p>

<ul class="hlist"><strong>Properties you may use</strong>:
<li><a target="_blank" href="http://xmlns.com/foaf/0.1/">foaf:fundedBy</a> <strong>(PREFERRED)</strong></li>
<li><a target="_blank" href="https://schema.org/funder">schema:funder</a></li>
</ul>

<h5>Example:</h5>
<pre>
@prefix owl: &lt;http://www.w3.org/2002/07/owl#&gt; .
@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt; .
@prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt; .
@prefix xsd: &lt;http://www.w3.org/2001/XMLSchema#&gt; .
&lt;https://w3id.org/fr/def/core#&gt; a owl:Ontology ;
foaf:funder &lt;https://example.org/fundingOrganization&gt; .
</pre>

<h4 class="list" id="funding">Funding [<em class="rfc2119" title="OPTIONAL">OPTIONAL</em>]</h4>
<p>
Projects or grants responsible for funding the vocabulary. Note that the range of this property is a schema:Grant.
</p>

<ul class="hlist"><strong>Properties you may use</strong>:
<li><a target="_blank" href="https://schema.org/funding">schema:funding</a> <strong>(PREFERRED)</strong></li>
</ul>

<h5>Example:</h5>
<pre>
@prefix owl: &lt;http://www.w3.org/2002/07/owl#&gt; .
@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt; .
@prefix schema: &lt;https://schema.org/&gt; .
@prefix xsd: &lt;http://www.w3.org/2001/XMLSchema#&gt; .
&lt;https://w3id.org/fr/def/core#&gt; a owl:Ontology ;
foaf:funding &lt;https://example.org/fundingGrant&gt; .
</pre>


<h3 id="cite" class="list">Vocabulary citation</h3>
<p>Ontologies are considered software, and should be cited as such [<a href="#soft">Smith et al 2016</a>]. However, researchers reusing the ontology may not refer to the correct citation associated to it. Adding metadata to help them would address this issue, granting you the appropriate credit for your work.</p>
Expand Down
38 changes: 20 additions & 18 deletions doc/bestPractices/sections/introduction-en.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,51 +53,53 @@ <h2 id="conv" class="list">Properties summary</h2>

Summary of <em class="rfc2119" title="RECOMMENDED">RECOMMENDED</em> properties for <strong>vocabularies</strong>
<ul class="hlist" id="rec">
<li><a href="#contributors">contributor</a></li>
<li><a href="#creationDate">creation date</a></li>
<li><a href="#creators">creator</a></li>
<li><a href="#description">description</a></li>
<li><a href="#lic">license</a></li>
<li><a href="#name">name</a></li>
<li><a href="#namespaceURI">namespace URI</a></li>
<li><a href="#prefix">prefix</a></li>
<li><a href="#previousVersion">previous version</a></li>
<li><a href="#title">title</a></li>
<li><a href="#description">description</a></li>
<li><a href="#versionIRI">version IRI</a></li>
<li><a href="#versionInfo">version info</a></li>
<li><a href="#previousVersion">previous version</a></li>
<li><a href="#creationDate">creation date</a></li>
<li><a href="#creators">creator</a></li>
<li><a href="#contributors">contributor</a></li>
<li><a href="#lic">license</a></li>
<li><a href="#name">name</a></li>
</ul>

Summary of <em class="rfc2119" title="OPTIONAL">OPTIONAL</em> properties for <strong>vocabularies</strong>
<ul class="hlist" id="opt">
<li><a href="#abs">abstract</a></li>
<li><a href="#status">status</a></li>
<li><a href="#backwardCompatibility">backward compatibility</a></li>
<li><a href="#biblio">bibliographic Citation</a></li>
<li><a href="#diagram">diagram</a></li>
<li><a href="#doi">DOI</a></li>
<li><a href="#extended">extended Ontologies</a></li>
<li><a href="#funder">funders</a></li>
<li><a href="#funding">funding grants</a></li>
<li><a href="#incompatibility">incompatibility</a></li>
<li><a href="#modificationDate">modification Date</a></li>
<li><a href="#issuedDate">issued date</a></li>
<li><a href="#source">source</a></li>
<li><a href="#publisher">publisher</a></li>
<li><a href="#doi">DOI</a></li>
<li><a href="#biblio">bibliographic Citation</a></li>
<li><a href="#logo">logo</a></li>
<li><a href="#diagram">diagram</a></li>
<li><a href="#modificationDate">modification Date</a></li>
<li><a href="#publisher">publisher</a></li>
<li><a href="#similar">see also</a></li>
<li><a href="#extended">Extended Ontologies</a></li>
<li><a href="#source">source</a></li>
<li><a href="#status">status</a></li>
</ul>

Summary of <em class="rfc2119" title="RECOMMENDED">RECOMMENDED</em> properties for <strong>classes and properties</strong>
<ul class="hlist" id="rec">
<li><a href="#label">label</a></li>
<li><a href="#def">definition</a></li>
<li><a href="#label">label</a></li>
</ul>

Summary of <em class="rfc2119" title="OPTIONAL">OPTIONAL</em> properties for <strong>classes and properties</strong>
<ul class="hlist" id="opt">
<li><a href="#example">example</a></li>
<li><a href="#deprecation">deprecation</a></li>
<li><a href="#status1">status</a></li>
<li><a href="#example">example</a></li>
<li><a href="#rationale">rationale</a></li>
<li><a href="#osource">source</a></li>
<li><a href="#status1">status</a></li>
</ul>


Expand Down
6 changes: 3 additions & 3 deletions doc/configuration/config.properties
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ contributorsInstitutionURI=https://isi.edu/;https://isi.edu/
description="A description of what the ontology does goes here"
diagram="https://example.org/diagram.svg"
DOI=
funder=
fundingGrant=
funders=
fundingGrants=
incompatibleWith=
issued=
images=image1.png;image2.png
Expand Down Expand Up @@ -45,4 +45,4 @@ extendedOntologyNames=test1; test2
extendedOntologyURIs=http://example.org/test1; http://example.org/test2
RDFXMLSerialization=ontology.xml
TurtleSerialization=ontology.ttl
N3Serialization=ontology.nt
NTSerialization=ontology.nt
21 changes: 13 additions & 8 deletions doc/configuration/configuration_doc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,21 +21,26 @@ contributorsInstitutionURI=https://isi.edu/;https://isi.edu/
description="A description of what the ontology does goes here"
diagram="https://example.org/diagram.svg"
DOI=
incompatibleWith=""
issued=""
funder=
fundingGrant=
incompatibleWith=
issued=
images=image1.png;image2.png
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
ontologyName=Example
ontologyPrefix=exo
modified="15 April, 2023"
ontologyNamespaceURI=https://w3id.org/example
previousVersionURI=https://w3id.org/example/1.0.0
publisher=
publisherURI=
publisherInstitution=
publisherInstitutionURI=
publisher=Ontology Engineering Group
publisherURI=https://oeg-upm.es
publisherInstitution=UPM
publisherInstitutionURI=https://www.upm.es
source=http://source1;http://source2
seeAlso=http://firstResource
ontologyTitle=The Example Ontology
thisVersionURI=https://w3id.org/example/1.0.1
ontologyRevisionNumber=v1.0.0
Expand All @@ -50,7 +55,7 @@ extendedOntologyNames=test1; test2
extendedOntologyURIs=http://example.org/test1; http://example.org/test2
RDFXMLSerialization=URL of the file with RDF-XML serialization. E.g., http://my-onto/onto.owl
TurtleSerialization=URL of the file with Turtle serialization. E.g., http://my-onto/onto..ttl;
N3Serialization=URL of the file with N3 serialization. E.g., http://my-onto/onto.n3
NTSerialization=URL of the file with N3 serialization. E.g., http://my-onto/onto.n3
JSONLDSerialization=URL of the file with JSON-LD serialization. E.g., http://my-onto/onto.jsonld
GoogleAnalyticsCode=UA-TestCodeGoesHere
contextURI=JSON-LD context URI.
Expand Down
46 changes: 42 additions & 4 deletions doc/metadataGuide/guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ In this document we illustrate how Widoco uses metadata in the final documentati
|vann |[http://purl.org/vocab/vann/](http://purl.org/vocab/vann/) |
|vcard |[http://www.w3.org/2006/vcard/ns#](http://www.w3.org/2006/vcard/ns#) |
|wdrs |[http://www.w3.org/2007/05/powder-s#](http://www.w3.org/2007/05/powder-s#) |
|widoco |[https://w3id.org/widoco/vocab#](https://w3id.org/widoco/vocab#) |

## Metadata usage in WIDOCO

Expand All @@ -51,6 +52,8 @@ The table below shows which ontology metadata annotations are recognized in WIDO
|Diagram |[foaf:image], [foaf:depiction], [schema:image]|diagram |[Sec 3.8.2] **[OPTIONAL]**|[Text]|[ontology](#onto), [config]|
|DOI |[bibo:doi] |DOI |[Sec 3.6.1] **[OPTIONAL]**|[Text]|[ontology](#onto), [config]|
|Extended ontologies| [voaf:extends] |extendedOntologyNames, extendedOntologyURIs | [Sec 3.4.6] **[OPTIONAL]**|[URI]|[ontology](#onto), [config]|
|Funders (org, person) |[foaf:fundedBy] [schema:funder] |funders |[Sec 3.5.4] **[OPTIONAL]**|[Text] or [URI]|[ontology](#onto), [config]|
|Funding grants |[schema:funding] |fundingGrant |[Sec 3.5.5] **[OPTIONAL]**|[Text] or [URI]|[ontology](#onto), [config]|
|Incompatible with|[owl:incompatibleWith] |incompatibleWith|[Sec 3.3.4] **[OPTIONAL]**|[URI] |[ontology](#onto), [config]|
|Imported ontologies|[owl:imports] |importedOntologyNames, importedOntologyURIs|**[RECOMMENDED]** (good practice in ontology engineering) | [URI] | [ontology](#onto), [config]|
|Issued date |[dct:issued], [schema:dateIssued]|issued |[Sec 3.4.4] **[OPTIONAL]**|[Text]|[ontology](#onto), [config]|
Expand All @@ -63,7 +66,7 @@ The table below shows which ontology metadata annotations are recognized in WIDO
|Previous version|[dce:replaces], [dct:replaces], [prov:wasRevisionOf], [pav:previousVersion], [owl:priorVersion]|previousVersionURI|[Sec 3.4.1] **[RECOMMENDED]**|[URI]|[ontology](#onto), [config]|
|Publisher|[dct:publisher], [dce:publisher], [schema:publisher]|publisher, publisherURI, publisherInstitution, publisherInstitutionURI|[Sec 3.5.3] **[OPTIONAL]**|[Text] or [Organization] or [BNode]|[ontology](#onto), [config]|
|Similar resources|[rdfs:seeAlso] | |[Sec 3.9] **[OPTIONAL]** |[Text] |[ontology](#onto), [config]|
|Status |[bibo:status] [mod:status] |status|[Sec 3.2.4] **[OPTIONAL]**|[Text] or [Status](#status)|[ontology](#onto), [config]|
|Status |[bibo:status] [mod:status] [schema:creativeWorkStatus] |status|[Sec 3.2.4] **[OPTIONAL]**|[Text] or [Status](#status)|[ontology](#onto), [config]|
|Source|[dce:source], [dct:source], [prov:hadPrimarySource], [wdrs:describedBy]|source|[Sec 3.4.5] **[OPTIONAL]** |[URI] |[ontology](#onto), [config]|
|Title |[dce:title], [dct:title], [schema:name] |ontologyTitle |[Sec 3.2.2] **[RECOMMENDED]**|[Text]|[ontology](#onto), [config]|
|Version IRI |[owl:versionIRI] |thisVersionURI |[Sec 3.3.1] **[RECOMMENDED]**|[URI] |[ontology](#onto), [config]|
Expand All @@ -73,6 +76,17 @@ The table below shows which ontology metadata annotations are recognized in WIDO

**\*\*** Configuration properties do not support [URI](#uri)s 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](#onto), [config]|
|N-Triples serialization |[widoco:ntSerialization] |NTSerialization |N/A **[OPTIONAL]** |[URL] |[ontology](#onto), [config]|
|JSON-LD serialization |[widoco:jsonldSerialization] |JSONLDSerialization |N/A **[OPTIONAL]** |[URL] |[ontology](#onto), [config]|
|RDF-XML serialization |[widoco:rdfxmlSerialization] |RDFXMLSerialization |N/A **[OPTIONAL]** |[URL] |[ontology](#onto), [config]|
|Turtle serialization |[widoco:turtleSerialization] |TurtleSerialization |N/A **[OPTIONAL]** |[URL] |[ontology](#onto), [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.
Expand Down Expand Up @@ -103,7 +117,8 @@ The following `Turtle` code block shows sample annotations for each of the metad
@prefix schema: <https://schema.org/> .
@prefix voaf: <http://purl.org/vocommons/voaf#> .
@prefix vann: <http://purl.org/vocab/vann/> .
@prefix bibo: <http://purl.org/ontology/bibo/>
@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> ;
Expand All @@ -123,7 +138,12 @@ The following `Turtle` code block shows sample annotations for each of the metad
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> ;
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:
Expand Down Expand Up @@ -203,15 +223,18 @@ 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/
description="A description of what the ontology does goes here"
description=A description of what the ontology does goes here
diagram="https://example.org/diagram.svg"
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
importedOntologyNames=Imported Ontology 1; Imported Ontology 2
importedOntologyURIs=http://example.org/test11; http://example.org/test22
issued=""
introduction=A brief text for the introduction section may be written here.
issued=
licenseURI=http://creativecommons.org/licenses/by/2.0/
licenseName=CC-BY
licenseIconURL=https://i.creativecommons.org/l/by/2.0/88x31.png
Expand All @@ -229,6 +252,10 @@ ontologyTitle=The Example Ontology
thisVersionURI=https://w3id.org/example/1.0.1
ontologyRevisionNumber=v1.0.0
status=Ontology Specification Draft
RDFXMLSerialization=ontology.xml
TurtleSerialization=ontology.ttl
NTSerialization=ontology.nt
JSONLDSerialization=ontology.nt
```

## Glossary (<a href="#table">Back to table</a>)
Expand Down Expand Up @@ -274,6 +301,8 @@ status=Ontology Specification Draft
[Sec 3.5.1]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#creators
[Sec 3.5.2]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#contributors
[Sec 3.5.3]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#publisher
[Sec 3.5.4]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#funder
[Sec 3.5.5]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#funding
[Sec 3.6.1]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#doi
[Sec 3.6.2]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#biblio
[Sec 3.7]: https://dgarijo.github.io/Widoco/doc/bestPractices/index-en.html#lic
Expand Down Expand Up @@ -324,6 +353,7 @@ status=Ontology Specification Draft
[doap:translator]: http://usefulinc.com/ns/doap#translator
[foaf:depiction]: http://xmlns.com/foaf/0.1/depiction
[foaf:family_name]: http://xmlns.com/foaf/0.1/family_name
[foaf:fundedBy]: http://xmlns.com/foaf/0.1/fundedBy
[foaf:givenname]: http://xmlns.com/foaf/0.1/givenname
[foaf:homepage]: http://xmlns.com/foaf/0.1/homepage
[foaf:image]: http://xmlns.com/foaf/0.1/image
Expand Down Expand Up @@ -362,6 +392,7 @@ status=Ontology Specification Draft
[schema:citation]: https://schema.org/citation
[schema:contributor]: https://schema.org/contributor
[schema:creator]: https://schema.org/creator
[schema:creativeWorkStatus]: https://schema.org/creativeWorkStatus
[schema:dateCreated]: https://schema.org/dateCreated
[schema:dateIssued]: https://schema.org/dateIssued
[schema:dateModified]: https://schema.org/dateModified
Expand All @@ -377,6 +408,8 @@ status=Ontology Specification Draft
[schema:publisher]: https://schema.org/publisher
[schema:schemaVersion]: https://schema.org/schemaVersion
[schema:url]: https://schema.org/url
[schema:funder]: https://schema.org/funder
[schema:funding]: https://schema.org/funding
[skos:definition]: http://www.w3.org/2004/02/skos/core#definition
[skos:editorialNote]: http://www.w3.org/2004/02/skos/core#editorialNote
[skos:example]: http://www.w3.org/2004/02/skos/core#example
Expand All @@ -394,3 +427,8 @@ status=Ontology Specification Draft
[vcard:hasURL]: http://www.w3.org/2006/vcard/ns#hasURL
[voaf:extends]: http://purl.org/vocommons/voaf#extends
[wdrs:describedBy]: http://www.w3.org/2007/05/powder-s#describedBy
[widoco:introduction]: https://w3id.org/widoco/vocab#introduction
[widoco:rdfxmlSerialization]: https://w3id.org/widoco/vocab#rdfxmlSerialization
[widoco:turtleSerialization]: https://w3id.org/widoco/vocab#turtleSerialization
[widoco:ntSerialization]: https://w3id.org/widoco/vocab#ntSerialization
[widoco:jsonldSerialization]: https://w3id.org/widoco/vocab#jsonldSerialization
Loading

0 comments on commit f1fa7b4

Please sign in to comment.