From aabf411ab3ce0a1ebbb251bad2aa18f50626a8c3 Mon Sep 17 00:00:00 2001 From: Giacomo Lanza <37865804+Zack-83@users.noreply.github.com> Date: Tue, 20 May 2025 10:38:15 +0200 Subject: [PATCH 1/2] Improve documentation for obsoletion Closes #2717 Adjust numbering, indenting and newlines; add allowed values for obsolescence reason --- principles/fp-019-term-stability.md | 37 +++++++++++++++++++---------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/principles/fp-019-term-stability.md b/principles/fp-019-term-stability.md index 212272824..5985123d3 100644 --- a/principles/fp-019-term-stability.md +++ b/principles/fp-019-term-stability.md @@ -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/). To obsolete a term, the ontology developer 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 and 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 and 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. To obsolete a term, the ontology developer SHOULD: -1) Indicate any exact term replacement: + +5. Indicate any exact term replacement: - 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: - OWL: Use the `oboInOwl:consider` annotation property with the value set to the full IRI(s) of the relevant term(s) ``` @@ -68,10 +69,20 @@ Note that some older implementations in OWL used the CURIE method as shown below ``` To obsolete a term, the ontology developer 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. +8. 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. + + +|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.| Examples ------- From f96272b7a8c287442a3fa73cac5357d04635ff89 Mon Sep 17 00:00:00 2001 From: Giacomo Lanza <37865804+Zack-83@users.noreply.github.com> Date: Wed, 21 May 2025 08:43:06 +0200 Subject: [PATCH 2/2] Apply suggestions from code review --- principles/fp-019-term-stability.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/principles/fp-019-term-stability.md b/principles/fp-019-term-stability.md index 5985123d3..f5be9a45e 100644 --- a/principles/fp-019-term-stability.md +++ b/principles/fp-019-term-stability.md @@ -48,10 +48,10 @@ It is not necessary (and not advisable) to delete the textual definition. To obsolete a term, the ontology developer SHOULD: -5. Indicate any exact term replacement: +1. Indicate any exact term replacement: - 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 -6. Indicate any inexact term replacements: +2. Indicate any inexact term replacements: - OWL: Use the `oboInOwl:consider` annotation property with the value set to the full IRI(s) of the relevant term(s) ``` @@ -69,21 +69,11 @@ Note that some older implementations in OWL used the CURIE method as shown below ``` To obsolete a term, the ontology developer MAY: -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. -8. Indicate the reason(s) for obsoleting: +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. - -|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.| - Examples -------