Skip to content

Improve documentation for obsoletion #2718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nataled merged 3 commits into from
May 21, 2025
Merged

Improve documentation for obsoletion #2718

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aabf411
Improve documentation for obsoletion
Zack-83 May 20, 2025
f96272b
Apply suggestions from code review
Zack-83 May 21, 2025
181c1b6
Merge branch 'master' into patch-1
nataled May 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 24 additions & 13 deletions principles/fp-019-term-stability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,21 +36,22 @@ Implementation
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/).

<i><b>To obsolete a term, the ontology developer</b></i> MUST:
1) Mark the term as obsolete
- OWL format: Add an "owl:deprecated" annotation property with value of "true^xsd:boolean"
- OBO format: Add an "is_obsolete: true" tag
2) Prepend the string "obsolete " (including the space) to the term label <i>and</i> the `editor preferred term` (IAO:0000111), if present
- NOTE: To be consistent with [Principle 12](https://obofoundry.org/principles/fp-012-naming-conventions.html) "Naming Conventions", the syntax/format MUST be precisely as given above (that is, the exact string as shown, lowercase and space included, with no other punctuation before or after). Thus, the following are disallowed: "Obsolete {label}", "obsolete_{label}", "OBSOLETE {label}" (and variations thereof).
3) Remove all existing logical axioms from the term
4) Remove or replace all usages of the term elsewhere in the ontology. For example, if an ontology has A part-of B, and B has been deprecated with replacement by C, then the corrected axiom would be A part-of C. Likewise, if A part-of B, and B part-of C, if B is deprecated, then any part-of axiom involving B MUST be removed; that is, by stating instead A part-of C.
1. Mark the term as obsolete:
- OWL format: Add an "owl:deprecated" annotation property with value of "true^xsd:boolean"
- OBO format: Add an "is_obsolete: true" tag
2. Prepend the string "obsolete " (including the space) to the term label <i>and</i> the `editor preferred term` (IAO:0000111), if present
- NOTE: To be consistent with [Principle 12](https://obofoundry.org/principles/fp-012-naming-conventions.html) "Naming Conventions", the syntax/format MUST be precisely as given above (that is, the exact string as shown, lowercase and space included, with no other punctuation before or after). Thus, the following are disallowed: "Obsolete {label}", "obsolete_{label}", "OBSOLETE {label}" (and variations thereof).
3. Remove all existing logical axioms from the term
4. Remove or replace all usages of the term elsewhere in the ontology. For example, if an ontology has A part-of B, and B has been deprecated with replacement by C, then the corrected axiom would be A part-of C. Likewise, if A part-of B, and B part-of C, if B is deprecated, then any part-of axiom involving B MUST be removed; that is, by stating instead A part-of C.

It is not necessary (and not advisable) to delete the textual definition.

<i><b>To obsolete a term, the ontology developer</b></i> SHOULD:
1) Indicate any exact term replacement:

5. Indicate any exact term replacement:
Comment thread
Zack-83 marked this conversation as resolved.
Outdated
- 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
- OBO: Use the `replaced_by:` tag with the value set to the CURIE of the relevant term
2) Indicate any inexact term replacements:
6. Indicate any inexact term replacements:
Comment thread
Zack-83 marked this conversation as resolved.
Outdated
- OWL: Use the `oboInOwl:consider` annotation property with the value set to the full IRI(s) of the relevant term(s)
```
<oboInOwl:consider rdf:resource="http://purl.obolibrary.org/obo/OBI_0001544")>
Expand All @@ -68,10 +69,20 @@ Note that some older implementations in OWL used the CURIE method as shown below
```
<i><b>To obsolete a term, the ontology developer</b></i> MAY:

1) Prepend the string "OBSOLETE. " (this precise string, including the space) to the term definition. NOTE: This MUST be implemented consistently. That is, if applied at all, it has to be applied to every obsoleted term definition.
2) Indicate the reason(s) for obsoleting:
- 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). See below for example.
- OBO: Use `relationship:` with the CURIE for the annotation property (IAO:0000231) and a CURIE for the specific reason (an individual from the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225)). See below for example. Note that older implementations often used alternative methods (described after the examples). These methods are still valid, but are not preferred.
7. Prepend the string "OBSOLETE. " (this precise string, including the space) to the term definition. NOTE: This MUST be implemented consistently. That is, if applied at all, it has to be applied to every obsoleted term definition.
Comment thread
Zack-83 marked this conversation as resolved.
Outdated
8. Indicate the reason(s) for obsoleting:
Comment thread
Zack-83 marked this conversation as resolved.
Outdated
- 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). See below for example.
- OBO: Use `relationship:` with the CURIE for the annotation property (IAO:0000231) and a CURIE for the specific reason (an individual from the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225)). See below for example. Note that older implementations often used alternative methods (described after the examples). These methods are still valid, but are not preferred.


|IRI |CURIE |Label |Definition|Editor note |
|---------------|-----------|-----------------------|----------|-------------- |
|obo:IAO_0000103|IAO:0000103|failed exploratory term|The term was used in an attempt to structure part of the ontology but in retrospect failed to do a good job|???|
|obo:IAO_0000226|IAO:0000226|placeholder removed |??? | ??? |
|obo:IAO_0000227|IAO:0000227|terms merged |???|An editor note should explain what were the merged terms and the reason for the merge. |
|obo:IAO_0000228|IAO:0000228|term imported|???|This is to be used when the original term has been replaced by a term imported from an other ontology. An editor note should indicate what is the URI of the new term to use.|
|obo:IAO_0000229|IAO:0000229|term split |???|This is to be used when a term has been split in two or more new terms. An editor note should indicate the reason for the split and indicate the URIs of the new terms created.|
|obo:OMO_0001000|OMO:0001000|out of scope |???|This obsolesence reason should be used conservatively. Typical valid examples are: un-necessary grouping classes in disease ontologies, a phenotype term added on the assumption it was a disease.|
Copy link
Copy Markdown
Contributor

@nataled nataled May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this is highly useful--and we agree it should be documented--we don't believe it should be on this principles page since it is more detailed than we'd like. There is a page (the OBO Academy "O-book" on obsoletion) that we already reference under Implementation (first sentence below that heading) which is intended to provide such details. We will look into having this information added there and, once done, will highlight that page again under the section mentioning the obsolescence reasons. We see that the same request was made under the ontology-metadata repo, so the information won't be lost. We thus ask that the table above be removed from your suggested changes.

Copy link
Copy Markdown
Contributor Author

@Zack-83 Zack-83 May 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fine. Implemented in OBOAcademy/obook#546

Comment thread
Zack-83 marked this conversation as resolved.
Outdated

Examples
-------
Expand Down