Skip to content

Commit 947ddac

Browse files
natalednataled
authored
Create fp-019-term-stability.md
1 parent 6363aa6 commit 947ddac

1 file changed

Lines changed: 119 additions & 0 deletions

File tree

‎principles/fp-019-term-stability.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
layout: principle
3+
id: fp-019-term-stability
4+
title: Stability of Term Meaning (principle 19)
5+
---
6+
7+
GO TO: [Recommendations/Requirements](#recommendations-and-requirements) | [Implementation](#implementation) | [Examples/Counter‑Examples](#examples) | [Criteria for Review](#criteria-for-review) | [Feedback/Discussion](#feedback-and-discussion)
8+
9+
Summary
10+
-------
11+
12+
The definition of a term MUST always denote the same thing(s)--known as "referent(s)"--in reality. If a proposed change to the definition would change its referents, then a new term with new IRI and definition MUST instead be created.
13+
14+
Purpose
15+
-------
16+
17+
Users of an ontology depend on the stability of its terms and their meanings. Therefore, changes to the definition of a term should never shift its meaning. Put another way, its set of referents MUST remain stable. That is, changes to a term definition should not cause that term to point to different entities than it denotes already.
18+
19+
Recommendations and Requirements
20+
-------
21+
22+
If changing a term definition would change its referent, then instead a new term MUST be created with a new IRI and the new definition. Minor changes to the definition for clarity, grammar, and/or proper punctuation that do not change the referent are permitted.
23+
24+
Conditions under which a term must be deprecated according to this principle, or for which term deprecation should be considered, include:
25+
26+
1) The old textual definition misses its intended target. This includes cases where the term refers to non-existent referents (as might happen, for example, when new research reveals that the referent does not exist in reality).
27+
1) The original term definition is considered sufficiently “damaged” (too vague, too restrictive, too misused or too misunderstood).
28+
29+
In all cases the developers SHOULD provide guidance on how to handle deprecated terms (either by exact replacement or by considering other terms), and be mindful of the potential costs to users of the ontology who might use the existing term. As well, developers SHOULD pre-announce term obsoletions. See [Principle 13](http://obofoundry.org/principles/fp-013-notification.html) for guidance on such announcements.
30+
31+
Implementation
32+
-------
33+
34+
Detailed procedures for obsoleting a term are described on the OBO Academy page [Obsoleting an Existing Ontology Term](https://oboacademy.github.io/obook/howto/obsolete-term/).
35+
36+
<i><b>To obsolete a term, the ontology developer</b></i> MUST:
37+
1) Mark the term as obsolete
38+
- OWL format: Add an "owl:deprecated" annotation with value of "true^xsd:boolean"
39+
- OBO format: Add an "is_obsolete: true" declaration
40+
1) Prepend the string "obsolete " (including the space) to the term label
41+
1) Prepend the string "OBSOLETE. " (including the space) to the term definition
42+
1) Remove existing logical axioms from the term
43+
1) Remove or replace all usages of the term elsewhere in the ontology
44+
45+
<i><b>To obsolete a term, the ontology developer</b></i> SHOULD:
46+
1) Indicate any exact term replacement:
47+
- OWL: Use the "term replaced by" annotation property from OMO ([IAO:0100001](http://purl.obolibrary.org/obo/IAO_0100001)) with the value set to the IRI of the relevant term
48+
- OBO: Use the "replaced_by:" tag with the value set to the CURIE of the relevant term
49+
1) Indicate any inexact term replacements:
50+
- OWL: Use the "oboInOwl:consider" annotation property with the value set either to the full IRI(s) or to the CURIE(s) of the relevant term(s)
51+
```
52+
IRI method: <oboInOwl:consider rdf:resource="http://purl.obolibrary.org/obo/OBI_0001544)>
53+
CURIE method: <oboInOwl:consider rdf:datatype="http://www.w3.org/2001/XMLSchema#string">OBI:0001544</oboInOwl:consider>
54+
```
55+
56+
- OBO: Use the "consider:" tag with the value set to the CURIE(s) of the relevant term(s)
57+
58+
<i><b>To obsolete a term, the ontology developer</b></i> MAY:
59+
60+
1) Indicate the reason(s) for obsoleting:
61+
- OWL: Use the "has obsolescence reason" annotation property from OMO ([IAO:0000231](http://purl.obolibrary.org/obo/IAO_0000231])) with the value set to the IRI of one of the individuals of the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225)
62+
- OBO: ??
63+
64+
<i><b>To obsolete a term, the ontology developer</b></i> MAY <i><b>(but probably shouldn’t)</b></i>:
65+
1) Place the term under "ObsoleteClass" or similar
66+
- OWL:
67+
```
68+
<rdfs:subClassOf rdf:resource=http://www.geneontology.org/formats/oboInOwl#ObsoleteClass/>
69+
```
70+
- OBO:
71+
```
72+
is_a: oboInOwl#ObsoleteClass
73+
```
74+
75+
Examples
76+
-------
77+
78+
The Ontology for Biomedical Investigations obsolete term "cell lysate MHC competitive binding assay using radioactivity detection" (OBI:0001574) can be deprecated as follows:
79+
80+
OWL:
81+
```
82+
<owl:Class rdf:about="http://purl.obolibrary.org/obo/OBI_0001574">
83+
<obo:IAO_0000111>obsolete cell lysate MHC competitive binding assay using radioactivity detection</obo:IAO_0000111>
84+
<obo:IAO_0000115>Competitive inhibition of binding assay measuring MHC ligand binding by radioactivity detection using MHC derived from a cell lysate</obo:IAO_0000115>
85+
<obo:IAO_0000231 rdf:resource="http://purl.obolibrary.org/obo/IAO_0000227"/>
86+
<obo:IAO_0100001 rdf:resource="http://purl.obolibrary.org/obo/OBI_0001544"/>
87+
<rdfs:label>obsolete cell lysate MHC competitive binding assay using radioactivity detection</rdfs:label>
88+
<owl:deprecated rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</owl:deprecated>
89+
</owl:Class>
90+
```
91+
92+
OBO:
93+
```
94+
[Term]
95+
id: OBI:0001574
96+
name: obsolete cell lysate MHC competitive binding assay using radioactivity detection
97+
def: "OBSOLETE. Competitive inhibition of binding assay measuring MHC ligand binding by radioactivity detection using MHC derived from a cell lysate." []
98+
is_obsolete: true
99+
replaced_by: OBI:0001544
100+
```
101+
102+
Counter-example
103+
-------
104+
105+
The PRO term "phosphoprotein" (PR:000037070) is defined as "A protein that includes at least one phosphorylated residue." A study finds 2000 more examples than was previously known. In this case, no new term needs to be made (nor the original deleted) because (1) the term definition did not change; and (2) the referent--proteins with a phophoresidue--did not change (that is, the newly-discovered phosphoproteins are just additional examples of that referent).
106+
107+
Criteria for review
108+
-------
109+
110+
TBD
111+
112+
Feedback and Discussion
113+
-------
114+
115+
To suggest revisions or begin a discussion pertaining to this principle, please [create an issue on GitHub](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/new?labels=attn%3A+Editorial+WG,principles&title=Principle+%2319+%22Stability%22of%22Term%22Meaning%22+%3CENTER+ISSUE+TITLE%3E).
116+
117+
To suggest revisions or begin a discussion pertaining to the automated validation of this principle, please [create an issue on GitHub]().
118+
119+
See also [this discussion](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/597) by the OBO Foundry Operations Committee focusing on term deprecation and [this discussion](https://github.com/OBOFoundry/OBOFoundry.github.io/issues/964) regarding the proposal of this principle.

0 commit comments

Comments
 (0)