Style guide additions

[rjyounes]

NB - Final list is below.

This list will be expanded over time:

• Describe formatting of annotations. Point to ontology shapes as a reference.
• Logical consistency (checking with a reasoner)
• Don't include owl:Thing and owl:NamedIndividual in definitions
• Specify a datatype on datatype properties (unless xsd:string, which is the default and also inserted by the serializer)
• Don't over-constrain properties with domains and ranges
• Distinctionary pattern for classes
• Role of OWL vs SHACL
• Cardinality restrictions vs someValuesFrom
• Avoid "orphan" classes
• Loosen recommendations on infixes in instances names. Most specific case is not always appropriate (see discussion thread in issue Should we convert gist to use our standard namespace conventions? #305). Make this a suggestion rather than a hard-and-fast rule.
• Use of rdfs:seeAlso where appropriate, rather than in definition or scope note.
• Is there more to say about datatype properties other than that they are nominal?
• Protege sorting issue: See Does the serializer give different results on a Protégé-generated file? #646. Both Contributing.md and the style guide should note that Protege editors need to:
  • Do a serialization and commit before editing.
  • Remove stub definitions added by Protege (skos annotation properties, etc.)

[rjyounes]

Adding comments from #581 in case there are some not covered above:

• Logical consistency (check with a reasoner)
• Specify a datatype range on datatype properties (except xsd:string)
• Generalize properties – don’t over-constrain with domains and ranges
• Ontology vs validation
• “Distinctionary” pattern for classes
  • E.g., ContingentEvent is an Event with start and end dates and some probability of occurrence
  • Note role of Open World Assumption here
• Avoid “orphan” classes

[Jamie-SA]

I looked at the style guide to see if it indicates if any annotation properties are required and I didn't see that. Do we expect that skos:prefLabel and skos:definition are required and should that be stated in the style guide?

[rjyounes]

Yes and yes. Thanks for catching that.

[rjyounes]

Some of these belong in a design pattern guide rather than the style guide. I'm removing those and providing the pared down list here:

• Describe formatting of annotations. Point to ontology shapes as a reference.
• Indicate required annotations - skos:prefLabel and skos:definition.
• Logical consistency (checking with a reasoner) - also add to Contributing.md
• pre-commit hook
• Use Oxford commas
• Specify a datatype on datatype properties (unless xsd:string, which is the default and also inserted by the serializer)
• Loosen recommendations on infixes in instances names. Most specific case is not always appropriate (see discussion thread in issue Should we convert gist to use our standard namespace conventions? #305). Make this a suggestion rather than a hard-and-fast rule.
• Use of rdfs:seeAlso where appropriate, rather than in definition or scope note.
• Is there more to say about datatype properties other than that they are nominal?
• Protege sorting issue: See Does the serializer give different results on a Protégé-generated file? #646. Both Contributing.md and the style guide should note that Protege editors need to:
  • Do a serialization and commit before editing.
  • Remove stub definitions added by Protege (skos annotation properties, etc.)