Terra Interoperability Model Best Practices

1. Use Standards

Reuse standard or commonly used vocabularies and ontologies where possible

Extend classes only when necessary

When classes/properties are extended from other vocabularies, use the naming conventions below rather than following the convention of the original source.

2. Define a URI Policy to create unique, persistent identifiers

The scope of this policy is the model itself, that is the concepts and properties that are defined by the Terra Interoperability Model.  The Model is not responsible for defining the URI policy for the data that uses the model, although following CURIE syntax is strongly recommended.

https://datamodel.terra.bio has been reserved for the Terra Interoperability Model.  As the model evolves, additional logical components will be managed separately and the URI will reflect this.  Thus the URI "https://datamodel.terra.bio/[Data Model Component]".  

3. Follow Naming Conventions

• General
  • Use meaningful, explicit and concise names
    • Note: the principle of URI Opacity still applies. 
  • Keep names as simple and short as possible
  • Expand abbreviations unless unwieldy or totally obvious
  • Provide definitions for new classes and properties
  • Provide a label (rdfs:label) for human readability
  • Avoid
    • Opaque class and property names, e.g. Class123456.
  • Class Names
    • Use PascalCase
    • Prefer singular nouns
  • Property Names
    • Use camelCase and start with lower case
    • Prefer multiple words and use of at least one upper case letter
    • Always use a present tense verb
    • For example, hasType, isDefinedBy
  • Identifiers
    • Use upper- and lower-case alphanumeric characters, numbers (except for the 1^st character)
    • Avoid
      • “.” (period), “-“ (hyphen) because they special characters in some implementation languages and may cause processing errors
      • “_” (underbar) because translation to snake_case may cause conflicts in names
      • using the same letters (but different case) to define 2 different entities, e.g., a property called “biosample” and a class named “BioSample" 

4. Provide Multi-lingual Support

• This is not required at this time.

5. Design Principles

• Design with Purpose
  • Focus the data model on a specific purpose.  For TIM, the purpose is findability and interoperability(future).
• Single Inheritance
  • Prefer to use ontologies/vocabularies by reference rather than by subclassing to avoid multiple inheritance.
• Identifiers
  • It is good practice to explicitly define an identifier property which is equivalent to the URI.  

References

• Best Practices
  • Best Practices for Publishing Linked Data
  • Data on the Web Best Practices
  • OBO Foundry Naming Conventions
  • Style Guidelines for Naming and Labeling Ontologies in the Multilingual Web
  • Pistoia Alliance Ontologies Guidelines for Best Practice
• Programming Language Conventions
  • Java Naming Conventions/
  • Scala Style Guide Naming Conventions
  • Style Guide for Python Code
• URI Policy
  • HCA URI Structure
  • Data on the Web Data Identifiers
• Principle of URI Opacity
  • Agents making use of URIs should not attempt to infer properties of the referenced resource. (See https://www.w3.org/TR/ld-bp/#HTTP-URIS)