Unit Vocabulary Submission Guidelines

This document describes the required procedures to submit a conforming unit to an existing unit vocabulary file, as well as the required metadata for submitting a new unit vocabulary file (such as a new domain-specific vocabulary). Please follow our git best practices.

Adding a unit to an existing vocabulary file (Recommended method)

Adding a new unit vocabulary file

Adding a unit to an existing vocabulary file. (Recommended method)

To add a new unit to the existing vocabulary, code should be added either directly to the file, or to a staging file in the /submissions folder (If there is uncertainty, please ask). Example entries are given below. The following 6 rules apply:

Qname naming rules

Of course, each qname must be unique in the unit: namespace.

Rule 1: Underscore: concept qualifiers will be separated from the unit and other qualifiers with underscores
```
Example:
GAL_IMP means "Imperial Gallon"
```
Rule 2: Concept qualifier type ordering

Rule 2.1: Dimensional qualifiers will be first to follow the unit. The default interpretation is mass.

      Example:
      LB_M is not needed for pound of mass - just LB
      OZ_VOL for volume (but also see rule 2.4 about jurisdictions)
      LB_F for pound of force

Rule 2.2: Context qualifiers will follow Dimensional qualifiers, and defaults to empty

  Example:
  GM_Carbon for grams of carbon

Rule 2.3: System qualifiers (e.g., _Metric, _Imperial, _SI) will follow Context qualifiers and defaults to _SI

  Example:
  TON_Metric for metric mass ton

Rule 2.4: Jurisdiction qualifiers (e.g., _UK, _US, _IT) follow System qualifiers

  Example: TON_US for US mass ton
           OZ_VOL_US for U.S. liquid ounce

Rule 2.5: Everything else is added to the end of the qualifier list, in alphabetical order, and defaults to empty

Rule 3: Numeric multipliers/prefixes aren't separated from the unit
```
Example:
MilliSEC
KiloGM
```
Rule 4: Exponents (power)

Number directly after a unit denotes that unit raised to the power of the number (cannot be negative)

  Example:
  M3 means "Cubic Meter"

Rule 5: Hyphens

a) - separates units that should be multiplied together

b) -PER- separates numerator units from denominator units
```
Example:
M-K-PER-W means "Meter * Kelvin / Watt"
```
c) There can be only 1 -PER- per qname

(For a discussion using a contributor's example, see Issue #129)
Rule 6: Order of Operations

The rules above should be applied (and interpreted) in the following order:

Qualifiers
Multipliers/Prefixes
Exponents (power)
Hyphens

Example: KiloM3 means (Kilometer)**3, or cubic kilometers, not Kilo(M**3), or 1000 cubic meters, because Prefixes precede Power. Thus, the conversionMultiplier to cubic meters is 10**9 rather than 10**3.

Required unit properties

The absolute minimum set of required properties are shown in the following example:

unit:M
  rdf:type qudt:Unit ;
  rdfs:label "Meter" ;
  qudt:conversionMultiplier "1"^^xsd:double ;
  qudt:conversionOffset "0.0"^^xsd:double ;
  qudt:plainTextDescription "The metric and SI base unit of distance.   The meter is equal to approximately 1.093 613 3 yards, 3.280 840 feet, or 39.370 079 inches."^^rdf:HTML ;
  qudt:hasQuantityKind quantitykind:Length ;
  rdfs:isDefinedBy <http://qudt.org/2.1/vocab/unit> ;
.

In other words,

rdf:type . qudt:Unit, and optionally any other qudt class names in the Unit class hierarchy
rdfs:label "Meter" . A human-readable label
qudt:conversionMultiplier . The multiplier to convert to the SI unit of this quantity kind
qudt:conversionOffset . The offset used to convert to the SI unit of this quantity kind
qudt:plainTextDescription . Some sort of description
qudt:hasQuantityKind . The appropriate quantity kind for this unit
rdfs:isDefinedBy . The graph this unit is defined in (which by convention is uniquely associated with the containing file)

There are additional recommended properties, shown in this excerpt. (Note that some of these are subject to revision in future versions)

unit:M
  a qudt:BaseUnit ;
  a qudt:LengthUnit ;
  a qudt:MKS-Unit ;
  a qudt:Unit ;
  qudt:abbreviation "m" ;
  qudt:code "1090" ;
  qudt:conversionMultiplier "1"^^xsd:double ;
  qudt:conversionOffset "0.0"^^xsd:double ;
  qudt:plainTextDescription "The metric and SI base unit of distance.   The meter is equal to approximately 1.093 613 3 yards, 3.280 840 feet, or 39.370 079 inches." ;
  qudt:hasQuantityKind quantitykind:Length ;
  qudt:id "U000E1090" ;
  qudt:longDescription "The metric and SI base unit of distance.  The 17th General Conference on Weights and Measures in 1983 defined the meter as that distance that makes the speed of light in a vacuum equal to exactly 299 792 458 meters per second. The speed of light in a vacuum, $c$, is one of the fundamental constants of nature. The meter is equal to approximately 1.093 613 3 yards, 3.280 840 feet, or 39.370 079 inches." ;
  qudt:symbol "m" ;
  qudt:ucumCaseInsensitiveCode "M"^^qudt:UCUMci-term ;
  qudt:ucumCaseSensitiveCode "m"^^qudt:UCUMcs-term ;
  qudt:ucumCode "M"^^qudt:UCUMci-term ;
  qudt:ucumCode "m"^^qudt:UCUMcs-term ;
  qudt:uneceCommonCode "MTR" ;
  skos:exactMatch <http://dbpedia.org/resource/Metre> ;
  skos:prefLabel "meter" ;
  prov:wasInfluencedBy <http://en.wikipedia.org/wiki/Metre?oldid=495145797> ;
.

All possible properties that could be included can be found in the QUDT Schema file /schema/SCHEMA_QUDT-v2.1.ttl in this repository.

Adding a new unit vocabulary

Adding an entirely new vocabulary involves some additional work related to defining an additional ontology along with the metadata for the ontology and the catalog entries needed to have it appear on the QUDT website. You can use the template vocabulary file found here can be used as a starting point. After making a copy of this template file, change all occurrences of:

"Template" to your vocabulary name
"2019-01-01" to the date of creation, publication, etc.
"9999" to an appropriate code number, if applicable
"Your name" to your name

One sample unit (with qname unit:ExampleTemplateUnit) is included in the template file, which can be used for reference and then deleted. Remember to change the file name according to the content being added. Below is the file naming convention used in QUDT: