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.

[rjyounes]

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

I agree.

Except you should say "scope notes" and "editorial notes"!

[pmcb55]

If we could do Markdown-like backticking in RDF I'd be thrilled, but that's not possible.

Yep, unfortunately.

I still don't think we need the single quotes.

Ok, so if I understand correctly, you're proposing scope notes and editorial notes, when referring to explicit gist terms having multiple values, but where the term name itself is singular (e.g., gist:hasMember), you'd mix-and-munge technically correct term names with just plain English (e.g., "...most precious gist:hasMembers from...")? Like this:

<my_favourite_pet_rock_collection> a gist:Collection ;
    skos:scopeNote "Not for sale - my most precious gist:hasMembers from around the world!"@en .

So I think that's not good (i.e., too much potential for confusion and ambiguity), but I do agree that single quoting all explicit term names is too noisy too.

Maybe I'd vote for adding an apostrophe and always just add an 's' (so not correct plain English (as it's not possessive), but at least it keeps the term name accurate) - and I'd use just 's even for plurals that in plain English would end in '-es' or '-ies', like gist:Mass and gist:Taxonomy respectively, e.g.:

<my_favourite_pet_rock_collection> a gist:Collection ;
    skos:scopeNote
        "Not for sale - my most precious gist:hasMember's from around the world!"@en ,
        "All Pet Rocks have their own personality, and their own gist:Mass's."@en ,
        "Their endless characteristics fall into so many different gist:Taxonomy's."@en .

The plural of 'Person' is (typically) 'People' (although 'Persons' can be fine in formal/legal contexts), but I still think the -'s convention works here too:

<pet_rock_collecting_team> a gist:Collection ;
    skos:scopeNote "My kick-ass team, with gist:Person's from my friends list!"@en .

[uscholdm]

Real examples from gist will be much easier to assess. We normally do not have scopeNotes for instances.

[uscholdm]

@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.

I prefer the first, I AM arguing against the use of the prefix.

[rjyounes]

Using apostrophe in plurals is a real pet peeve of mine, that would drive me crazy.

@pmcb55 The fact of the matter is, if we give preference to ordinary language, the use of ontology terms is going to be quite rare, and the possible misunderstandings even rarer, so I don't think we need to angst over this one too much. In fact, none of your examples are cases where we would use the ontology terms, based on what we've said, and the plural case may never arise. I'm thinking of something like:

skos:editorialNote "Consider making this a subclass of gist:Network."

I'm neutral about prefixes, but would prefer no single quotes and no apostrophes.

[pmcb55]

Hi @rjyounes - yeah, that's all fair enough. Really, I'm just extremely impressed with the level of consideration and discussion here (and the fact that it's all been recorded in a public record, so we can always refer back to these points-of-view in future).

[rjyounes]

DECISION:

1. Use plain English unless a scopeNote, for example, needs to refer to specific classes/properties
2. In that case, use gist: in front of it.

TO DO:

• Add to style guide (Rebecca)
• Implementation (Brett, Peter) (Break up into two issues)

[rjyounes]

Combine into a single PR with issue #511.