Style Guide

[neilotte]

We will be creating a style guide for the maintenance of CCO, which we can refer to for both quality control as well as guidance to developers. If anyone wants to contribute to this document, please feel free to place ideas or recommendations here.

@johnbeve @alanruttenberg @mark-jensen @APCox @cameronmore

[swartik]

The guide needs to describe the git workflow(s) used to maintain CCO.

[neilotte]

@johnbeve and @mark-jensen have been working on that for us and we will certainly be publishing this as soon as we are able.

[cameronmore]

Definition sources need some guidelines, in particular:

1. The priority and quality of sources. For example, should we prioritize a Merriam Webster source or Oxford English Dictionary Source? Or prefer sources from Standards documents, when relevant.
2. How to Cite Sources For online resources, a URI seems appropriate, but should we use dc terms bibliographic citation for articles and books? What citation style should we use? (APA or MLA is common, I personally prefer Chicago). Also, should the value of the annotation be, strictly a URI or citation or looser like "Adapted from [insert source]" or "Quotes from [insert source]". Or, a case by case basis.

[alanruttenberg]

Commit messages should mention the issue they address. E.g. see linking a pull request to an issue
But you can mention an issue in a commit message that doesn't necessarily close the issue using #<issue number>

[alanruttenberg]

If an issue is moved to a discussion (I've related to Neil Otte my concern that this isn't necessarily a good practice) please include the link to the discussion.

[neilotte]

Hi Alan, "please include the link to the discussion" where?

[neilotte]

Also, note that there are two ways to move something into discussion. First, you can re-create a discussion thread and cite tickets that have been closed and link to them; however, github encourages the full transfer of a thread directly into a discussion. One can do this by selecting the 'transfer to discussion' link which is the right of each issue. I think where the full thread is appropriate for continuing the discussion, the latter is preferred and I will lean towards this. The former is preferred where one wishes to consolidate an issue with the concensus of the respondents.

[alanruttenberg]

In the original issue(s).

[cameronmore]

A clear versioning policy should also be included--how to version the smaller modules and / or the larger combined file, and maybe some guidelines for 'when it makes sense to cut a release'? That might be too hard to quantify in detail.

[swartik]

When you talk about versioning the smaller modules and/or the combined file, are you referring to:

• The owl:versionInfo annotation?
• The ontology version IRI?
• A git tag?

Or something else?

[cameronmore]

all? and more? Don't need to be a super long part, but just part of the dev process that needs to be stated as part of a procedure

[alanruttenberg]

SPARQL Queries with opaque ids in the are difficult to read. I have a practice of creating prefixes for such terms and then using the prefixes where the opaque ids would be, and propose this should be the documented style for queries that are part of the CCO distribution.

For example, In the #733 design pattern PR, we have a query:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> 
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> 
PREFIX cco: <https://www.commoncoreontologies.org/> 
PREFIX obo: <http://purl.obolibrary.org/obo/> 
PREFIX owl: <http://www.w3.org/2002/07/owl#> 

SELECT ?document ?document_field
WHERE {
  ?document obo:BFO_0000178 ?document_field . #has continuant part
  ?document a cco:ont00001298 . #document 
  ?document_field a cco:ont00001243 . #document field
}

I would write:

PREFIX cco: <https://www.commoncoreontologies.org/> 
PREFIX obo: <http://purl.obolibrary.org/obo/> 
PREFIX document: <https://www.commoncoreontologies.org/ont00002039> # Material copy of a Document
PREFIX has_part: <http://purl.obolibrary.org/obo/BFO_0000178> # has continuant part
PREFIX field: <https://www.commoncoreontologies.org/ont00001243> # Material copy of a document field"

SELECT ?document ?document_field
WHERE {
  ?document has_part: ?document_field . 
  ?document a document:. 
  ?document_field a field:.
}

Note that I have removed unused prefixes.

Writing queries in this style makes them much easier to understand and develop, particularly when the query gets larger.

(It also made me realize the pattern is wrong, being based on an IBE instead of an ICE)

[neilotte]

Interesting @alanruttenberg . Thanks for sharing.

[swartik]

@alanruttenberg, that certainly improves readability.

1. The document: prefix ends with a slash. Was that intentional?
2. I propose that the prefix name be the rdfs:label annotation, with underscores replacing spaces. Yes, it's more verbose, but it will standardize names across queries.

[alanruttenberg]

@swartik the slash was a mistake. Thanks for catching it - fixed now.

On the subject of prefixes I'm mixed. The downsides to insisting that the prefix be the label are

• For labels that have special characters, escaping will be ugly
• Keeping capitalization makes typing harder. You may remember I advocate for lower case labels as OBO does.
• The length of labels may detract from the quick comprehensibility that shorter labels give. Do we really want to insist that all those "X information content entity" terms be written out in full? The repeated "information content entity" in a query that deals with multiple of them will likely appear as noise, making comprehension harder. On the other hand, it's relatively unburdensome to remember a handful of shorter handles listed in the prefix section.

The fact that prefixes are local gives us the freedom to write queries in a comfortable way, without, for the most part, having to worry about incompatibilities across queries.

That said, there's something to be said for being able to read consistently over a selection of queries that form a logical unit, or which are dedicated to the same use case - cases where it is not unlikely that the user will be reviewing several queries from the set.

Overall, I would leave discretion to the query writer, but provide guidance like the above that explains the considerations about naming prefixes, and then also review queries as they come in to be able to identify those cases where prefix use is suboptimal and suggest that the writer make changes.

Finally, to make it easier on query writers, we could have a shorthand for the prefixes, expanded using a script. For instance instead of having to write

PREFIX field: <https://www.commoncoreontologies.org/ont00001243> # Material copy of a document field"
PREFIX has_part: <http://purl.obolibrary.org/obo/BFO_0000178> # has continuant part

The author could write

field,ont00001243
has_part,BFO_0000178

or

field,Material Copy of a Document Field
has_part,has continuant part

and have a python script that reads the ontology and expands that into the longer prefix line. I volunteer to write such a script if we decide that's a useful tool. rdflib makes that relatively easy.

[swartik]

@alanruttenberg With the query:

PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?entity ?type ?label
WHERE {
  ?entity rdfs:label ?label ; a ?type
  FILTER (?type in (owl:Class, owl:ObjectProperty, owl:DatatypeProperty))
  FILTER (! REGEX(str(?label), "^[-a-zA-Z0-9 ]+$"))
}

I only find one problematic label: "Emergency AC/DC Power Source". There are 16 more if you include individuals, but I doubt query writers will use individuals much.

Anyway, I didn't mean to imply I favored imposing hard-and-fast rules. Best practices will be enough.