Define best practice for using or not using ontology terms in annotations

[rjyounes]

For example, the definition of gist:OrderedCollection is

skos:definition "A collection in which the members are sequentially ordered. All members of an OrderedCollection are OrderedMembers."^^xsd:string ;

I prefer the use of ordinary English language instead, or at the minimum consistency. (This one is inconsistent because "collection" is not referred to by the class name "Collection."). In this case:

skos:definition "A collection in which the members are sequentially ordered. All members of an ordered collection are ordered members."^^xsd:string ;

[pmcb55]

Yep - I totally agree with this.
A further justification I think is that the current definition:

skos:definition "A collection in which the members are sequentially ordered. All members of an OrderedCollection are OrderedMembers."^^xsd:string ;

...doesn't tell us what ontology defines these OrderedCollection and OrderedMember terms (yeah, we know they're from gist, but how would someone unfamiliar with gist, but reading this definition in isolation, know that for sure?). So to be clearer in it's current form, I think this would be a slight improvement:

skos:definition "A collection in which the members are sequentially ordered. All members of an gist:OrderedCollection are gist:OrderedMembers."^^xsd:string ;

...but now that raises the point that the 2nd term there isn't gist:OrderedMembers, it's gist:OrderedMember, so then we'd need to fix that, maybe with punctuation like this:

skos:definition "A collection in which the members are sequentially ordered. All members of an gist:OrderedCollection are gist:OrderedMember's."^^xsd:string ;

...but that's certainly not great either...

Yet another justification would be the common human-nature case (in general programming) of term names being renamed/refactored, but the developer forgetting to update (or not finding) all the associated referencing comments/definitions to reflect the new term name. So all comments/descriptions/definitions should always try and avoid explicit references anyway, and instead try to describe in general, abstract terms.

So in other words(!), I agree with @rjyounes - just use ordinary English ;) !

[dylan-sa]

I agree that it's good to use ordinary English terms as much as possible. However, sometimes there are good reasons to use the ontology terms instead.

1. If you need to refer to the ontology term itself to make the point:

skos:scopeNote "Each NetworkLink is connected to a NetworkNode via the property 'gist:links' or one of its subproperties."^^xsd:string 

Here, reference to the property gist:links is crucial to the message being communicated. If we rephrased using the ordinary English 'links', the point would be lost.

2. If you want to make it clear that you mean something in a specific, technical sense:

skos:scopeNote "Often a 'bucket' can be modeled either as an owl:Class or as a gist:Category.

Here, we could rephrase using just 'class' or 'category', but those who are unfamiliar with the distinction may lose out on the point.

So, while ordinary English should be generally preferred, I think using ontology terms in at least some annotations is unavoidable. The question then becomes how to use them. Building from some of @pmcb55's points, I think using the gist namespace prefix is helpful. I think single quotes around the ontology terms looks OK, and you can add an 's' after them when needed. For example: A 'gist:OrderedCollection' has 'gist:OrderedMember's.

[rjyounes]

@dylan-sa I mostly agree, and meant to mention an exception when there is an explicit reference to an ontology term rather than the concept it represents, but apparently forgot.

I like @pmcb55's suggestion to use the gist: prefix when citing ontology terms; although the specific example "A 'gist:OrderedCollection' has 'gist:OrderedMember's" is one where I would suggest not using ontology terms.

However, for consistency, in a single annotation either all or none of the references should be prefixed ontology terms, so

skos:scopeNote "Each NetworkLink is connected to a NetworkNode via the property 'gist:links' or one of its subproperties."

should be

skos:scopeNote "Each gist:NetworkLink is connected to a gist:NetworkNode via the property gist:links or one of its subproperties."

I think the use of single quotes adds visual clutter without any benefit - gist:links is clearly an ontology term without quoting it.

[uscholdm]

I don't like using the prefix gist: in annotations because of course its gist. If its NOT gist, then use a prefix.

Perhaps we could say never use ontology terms in definitions, just plain English. Use them as needed in scopeNotes or editorialNotes

[rjyounes]

See also the discussion in #497.

[pmcb55]

Hi @uscholdm - interesting, but just personally, I don't think I agree with this assertion:
"I don't like using the prefix gist: in annotations because of course its gist"

A very general rule-of-thumb for me is to never rely on any implicit (or contextual, or out-of-band) knowledge - simply 'cos that implicitness tends to bite you later when pesky humans (i.e., your users/customers/3rd-party-developers) re-use these comments/definitions outside of their originally intended context - e.g., when these gist skos:definition's are displayed to humans on a webpage that also displays definitions of terms from multiple different/non-gist ontologies.

But also, even just aesthetically, from a reading-English-prose perspective, I don't see the inclusion of an explicit gist: prefix (when referring to specific terms) as being confusing, or 'noisy', or 'getting in the way' of comprehension - but is one of those reasons the root of your dislike...?

[uscholdm]

Aesthetically, I prefer:

• The OrderedCollection hasMember at least one OrderedMember,
• The gist:OrderedCollection gist:hasMember at least one gist:OrderedMember

More concise, more readable, less clunky, the chance of ambiguity is negligible. A matter of preference. We can agree to disagree and see what others think.

[pmcb55]

Again, just my 2c, but I think I'd disagree with @rjyounes here:

I think the use of single quotes adds visual clutter without any benefit - gist:links is clearly an ontology term without quoting it.

I do think the back-ticking definitely helps in making it clear that gist:links is the actual term, but I think the problem I'm alluding to is somewhat hidden by the inherent 'plural-ness' of that particular term. I guess my point really only arises for singular term names that can naturally have multiple values, like gist:hasMember...

[uscholdm]

There is one other factor. If we use actual property and class IRIs in the comments it makes it possible to automate changes in other annotations that refer to a concept if the name changes. Otherwise it's a bit of a hit or miss manual exercise. Tradeoffs, as always.

[rjyounes]

This is a good point, but on the other hand, if we use actual English words, we may not have to make changes to annotations, as long as the semantics haven't changed and the annotation still holds true.

[rjyounes]

@pmcb55

I do think the back-ticking definitely helps

If we could do Markdown-like backticking in RDF I'd be thrilled, but that's not possible. I still don't think we need the single quotes.

[rjyounes]

@uscholdm

When you say:

Aesthetically, I prefer:

* The OrderedCollection hasMember at least one OrderedMember,
* The gist:OrderedCollection gist:hasMember at least one gist:OrderedMember

do you mean you prefer the first to the second? I thought you were arguing against the use of the prefix.