Skip to content

Latest commit

 

History

History
111 lines (75 loc) · 4.48 KB

gistStyleGuide.md

File metadata and controls

111 lines (75 loc) · 4.48 KB

gist Style Guide [ IN PROGRESS ]

Purpose of this document

The purpose of this document is two-fold:

  • Define and implement conventions in order to standardize gist.
  • Articulate what we consider best or "better" practices for ontology design and implementation.

OWL Version

gist uses OWL 2 DL.

Serialization

  • gist OWL files are serialized in RDF Turtle
  • The EDM Council's RDF serialization tool, rdf-toolkit.jar, should be run before every commit in order to standardize formatting and eliminate noise in git diffs.
  • It is recommended to run this as a pre-commit hook in your git repository to ensure that it is done every time. In order to use the standard settings, copy the provided pre-commit script from the tools/ directory in the repository to .git/hooks/ after the repository is cloned, and ensure that JAVA_HOME is set in your environment. This script will only format RDF files, ignoring all others.

Naming

Local names

Classes

  • Camelcase with initial uppercase
  • Acronyms are also camelcased so that word boundaries are unambiguous.
    • Examples: AmaGuideline, not AMAGuideline; UriScheme, not URIScheme
    • ID is an exception, because Merriam-Webster spells it in all-caps.
  • Alphanumeric characters only.
    • Example: Isbn10, not Isbn-10 or ISBN-10.

Properties

  • Camelcase with initial lowercase
  • Acronyms as above

All

  • No non-standard abbreviations. E.g., hasUoM should be hasUnitOfMeasure.

Labels

Classes

  • Sentence case
  • Normalized to natural language standards. E.g., hyphens inserted, acronyms in all caps, etc.
    • Examples: AMA guideline, ISBN-10

Properties

  • Same as classes, but initial lowercase
  • Examples: has unit of measure, has SSN.

Rationale

We adopt sentence over title case because the latter, while technically well-defined, has more complex rules and can introduce inconsistencies when implemented by different users.

Annotations

gist uses SKOS annotations rather than rdfs:label and rdfs:comment. The accepted annotations, intended use, and previous usage are shown in the following tables. Refer to the SKOS ontology for formal definitions.

Preferred SKOS annotations

Annotation Use Instead Of
skos:prefLabel Preferred label rdfs:label
skos:altLabel Alternative label, where relevant n/a
skos:definition Definition rdfs:comment
skos:scopeNote Additional clarifying comments about the meaning or usage of a term rdfs:comment
skos:example One or more examples rdfs:comment
skos:editorialNote Notes for editors rdfs:comment

RDFS annotations

Certain RDFS annotations are recommended where there is no SKOS equivalent.

Annotation Use
rdfs:seeAlso Indicates a resource that may provide additional information about the subject. Preferably points to a web page or RDF resource rather than text.
rdfs:isDefinedBy Identifies the ontology module the term is defined in. Added automatically during gist release bundling and does not needed to be added by hand.

Use only rarely

Annotation Comment
skos:changeNote Normally change notes are provided by the git history or version comparison.
skos:historyNote Normally change notes are provided by the git history or version comparison.
skos:note A more specific annotation is preferred.

Do not use

Annotation Instead Use
rdfs:label skos:prefLabel
rdfs:comment All other annotations, especially skos:scopeNote and skos:example

Rationale

SKOS annotations allow a more fine-grained approach to human-readable documentation. This change also aligns with emerging common practice.

Documentation

Documentation is generally written in Markdown, and a Markdown linter should be applied to flag and fix Markdown rule violations. The Markdown config file markdownlint.json configures the Markdown delinter. If using VS Code as an editor, markdownlint is a helpful extension that provides code hints and can be configured to automatically correct errors.