INCATools / INCATools/kgcl

Non-obvious side-effects of KGCL changes should be explicitly specified

Open
#52 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
23
Forks
5
PR merge metrics
No merged PRs in 30d

Description

(This is a follow-up to [this issue in KGCL-Java](https://github.com/gouttegd/kgcl-java/issues/2), itself a follow-up to [another issue in ENVO](https://github.com/EnvironmentOntology/envo/issues/1480).)

There is apparently an expectation that some KGCL change operations should have some kind of “side effects” that go beyond the strict application of the change itself.

In the case at hand, it is seemingly expected that obsoleting a class should result in the automatic removal of any axiom that refers to that class. If so, that expected behaviour should be explicitly specified somewhere.

I can imagine at least 3 different ways of dealing with axioms referring to a to-be-obsoleted class:

* Silently and automatically removing them. That’s apparently with KGCL-Python does.
* Leave them in place for an editor to decide what to do with them. That’s what KGCL-Java does.
* Refusing to perform the operation and warn the user (“This class is referred to by several other classes, obsoleting it would have cascading effects. I’m sorry Dave, but I’m afraid I can’t do that.”).

I have no strong opinion on which behaviour is best, and I have no objection to amending KGCL-Java to implement the first one if it is indeed the behaviour intended by KGCL’s authors. But my point is that all those possible behaviours are arguably equally reasonable, and that implementers cannot be expected to guess which was the “intended one”. Right now, the spec in effect leaves this kind of decision at the discretion of implementations, so unsurprisingly, different implementations make different decisions. If a consistent behaviour is desired, the spec must says so.

---
For node obsoletions, do we agree that the expected behaviours are as follows:

* For node obsoletion without replacement or alternative (i.e. `NodeObsoletion` proper): remove any axiom referring to the to-be-obsoleted entity.
* For node obsoletion with direct replacement: rewrite any axiom referring to the to-be-obsoleted entity to make it refer to the replacement entity instead (in this case, the spec does say that it _can_ be done, but does not say it _has_ to be done; my interpration was that the replacement was again left for the editors to do, and that the only expectation from KGCL was to set the `replaced_by` annotation).
* For node obsoletion with non-direct replacement(s): presumably remove any referring axiom (as in the case of obsoletion without replacement at all)? Though I would think it is more useful to leave them in place so that editors are aware of the fact they need to manually rewrite them with one of the suggested alternative terms.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the KGCL specification and the linked KGCL-Java and ENVO issues, focusing on node obsoletion and axioms that refer to obsolete entities. Document a single, explicit behavior for obsoletion without replacement, with direct replacement, and with non-direct alternatives, so implementations no longer need to choose independently.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.