Creating a brand new unit ‐ minimum approach - qudt/qudt-public-repo GitHub Wiki

Here is a sequence of events for a person doing the minimum for defining a new unit. This would normally be done in a new branch (say, new-branch) off of the main branch in a user's fork of the QUDT public repo. It also assumes you have installed the Maven package as instructed here.

Basically, you will repeat the following loop until you get no errors:

image

First, create a new edit in src/main/rdf/vocab/unit/VOCAB_QUDT-UNITS-ALL.ttl

unit:RANDOM-M-SEC
a qudt:Unit ;
.

Then, from the root of your fork in new-branch, run

mvn clean; mvn spotless:apply; mvn install

Output: ...lots of messages, ending with:


[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:24 min
[INFO] Finished at: 2025-10-17T11:08:55-04:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.github.qudtlib:rdfio-maven-plugin:1.5.5:pipeline (main) on project qudt-public-repo: Error executing PipelineMojo: Pipeline stopped by <stop> step: Data errors in src/main/rdf/dist!
[ERROR]
[ERROR]                                                             to fix the errors in `src`, do NOT run mvn clean - the
[ERROR]                                                             current build output is needed!
[ERROR]                                                             Just run:
[ERROR]
[ERROR]                                                             mvn -Pfix install

(A note of interest. If you want to see what errors are going to be fixed in this next step, you can see what it will do in the file target/src-errors/errors.txt)

OK, so I need to run the following:

mvn -Pfix install

...which modifies the source file as follows:

unit:RANDOM
  a qudt:ContextualUnit, qudt:Unit ;
  rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> .

unit:RANDOM-M-SEC
  a qudt:Unit ;
  qudt:conversionMultiplier 0.0 ;
  qudt:conversionMultiplierSN 0.0E0 ;
  rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> .

A couple of things to note in the modified file:

  1. A new component unit has been stubbed in, and declared a qudt:ContextualUnit because it is unknown and not built out of any known units.
  2. A conversion multiplier of 0.0 has been added. That's because nothing is known about the magnitude of RANDOM. So, let's try the build again
mvn install

The output ends with:

[INFO]         SHACL VALIDATION REPORT
[INFO]         =======================
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM
[INFO]         Focus node: Violation
[INFO]         Message   : A rdfs:label is required.
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM
[INFO]         Focus node: Violation
[INFO]         Message   : Property needs to have at least 1 value
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM-M-SEC
[INFO]         Focus node: Violation
[INFO]         Message   : A rdfs:label is required.
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM-M-SEC
[INFO]         Focus node: Violation
[INFO]         Message   : Property needs to have at least 1 value
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE

OK, I manually add the missing triples:

unit:RANDOM
  a qudt:ContextualUnit, qudt:Unit ;
  rdfs:label "RANDOM" ;
  rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> .

unit:RANDOM-M-SEC
  a qudt:Unit ;
  qudt:conversionMultiplier 0.0 ;
  qudt:conversionMultiplierSN 0.0E0 ;
  rdfs:label "RANDOM-M-SEC" ;
  rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> .

...and get the following error after running 'mvn install'

[ERROR] Run 'mvn spotless:apply' to fix these violations.
[ERROR] -> [Help 1]

This command will re-serialize the file. So, from now on, I remember to run mvn spotless:apply before running mvn install

mvn spotless:apply; mvn install

Now I get this error:

[INFO]         SHACL VALIDATION REPORT
[INFO]         =======================
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM
[INFO]         Focus node: Violation
[INFO]         Message   : unit:RANDOM: dimension vector is missing and no way to derive it (no qudt:scalingOf, no qudt:hasFactorUnit present)
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE

So, add a dimension vector. I'm choosing to make this new unit dimensionless. Here's the edited source:

unit:RANDOM
  a qudt:ContextualUnit, qudt:Unit ;
  qudt:hasDimensionVector qkdv:A0E0L0I0M0H0T0D1 ;
  rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> ;
  rdfs:label "RANDOM" .

unit:RANDOM-M-SEC
  a qudt:Unit ;
  qudt:conversionMultiplier 0.0 ;
  qudt:conversionMultiplierSN 0.0E0 ;
  rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> ;
  rdfs:label "RANDOM-M-SEC" .

Run the build again:

mvn spotless:apply; mvn install

...again giving me the build failure:

[ERROR]                                                             mvn -Pfix install

This time, it has more information to work with, so it has more additions. OK, run that again:

mvn -Pfix install

Now the source looks like:

unit:RANDOM
a qudt:ContextualUnit, qudt:Unit ;
qudt:conversionMultiplier 0.0 ;
qudt:conversionMultiplierSN 0.0E0 ;
qudt:hasDimensionVector qkdv:A0E0L0I0M0H0T0D1 ;
rdfs:label "RANDOM" ;
rdfs:label "RANDOM"@en .
  
unit:RANDOM-M-SEC
a qudt:ContextualUnit, qudt:Unit ;
qudt:conversionMultiplier 0.0 ;
qudt:conversionMultiplierSN 0.0E0 ;
qudt:hasDimensionVector qkdv:A0E0L1I0M0H0T1D0 ;
rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> ;
rdfs:label "RANDOM Meter Second"@en-US ;
rdfs:label "RANDOM Metre Second" ;
rdfs:label "RANDOM Metre Second"@en .

...but there are also lots of new errors reported:

[INFO]         SHACL VALIDATION REPORT
[INFO]         =======================
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM
[INFO]         Focus node: Violation
[INFO]         Message   : <http://qudt.org/vocab/unit/RANDOM>: The value of rdfs:label, 'RANDOM', is not in title case.
[INFO]         - each word must start with an uppercase letter
[INFO]         - no uppercase letters allowed directly after a lowercase letter (no CamelCase)
[INFO]         - articles and prepositions must be lowercase
[INFO]
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM
[INFO]         Focus node: Violation
[INFO]         Message   : <http://qudt.org/vocab/unit/RANDOM>: The value of rdfs:label, 'RANDOM'@en, is not in title case.
[INFO]         - each word must start with an uppercase letter
[INFO]         - no uppercase letters allowed directly after a lowercase letter (no CamelCase)
[INFO]         - articles and prepositions must be lowercase
[INFO]
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM-M-SEC
[INFO]         Focus node: Violation
[INFO]         Message   : <http://qudt.org/vocab/unit/RANDOM-M-SEC>: The value of rdfs:label, 'RANDOM Meter Second'@en-US, is not in title case.
[INFO]         - each word must start with an uppercase letter
[INFO]         - no uppercase letters allowed directly after a lowercase letter (no CamelCase)
[INFO]         - articles and prepositions must be lowercase
[INFO]
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM-M-SEC
[INFO]         Focus node: Violation
[INFO]         Message   : <http://qudt.org/vocab/unit/RANDOM-M-SEC>: The value of rdfs:label, 'RANDOM Metre Second', is not in title case.
[INFO]         - each word must start with an uppercase letter
[INFO]         - no uppercase letters allowed directly after a lowercase letter (no CamelCase)
[INFO]         - articles and prepositions must be lowercase
[INFO]
[INFO]
[INFO]         Severity  : http://qudt.org/vocab/unit/RANDOM-M-SEC
[INFO]         Focus node: Violation
[INFO]         Message   : <http://qudt.org/vocab/unit/RANDOM-M-SEC>: The value of rdfs:label, 'RANDOM Metre Second'@en, is not in title case.
[INFO]         - each word must start with an uppercase letter
[INFO]         - no uppercase letters allowed directly after a lowercase letter (no CamelCase)
[INFO]         - articles and prepositions must be lowercase
[INFO]
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE

OK, edit the source to address those errors (titlecase labels)

unit:RANDOM
a qudt:ContextualUnit, qudt:Unit ;
qudt:conversionMultiplier 0.0 ;
qudt:conversionMultiplierSN 0.0E0 ;
qudt:hasDimensionVector qkdv:A0E0L0I0M0H0T0D1 ;
rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> ;
rdfs:label "Random" ;
rdfs:label "Random"@en .

unit:RANDOM-M-SEC
a qudt:ContextualUnit, qudt:Unit ;
qudt:conversionMultiplier 0.0 ;
qudt:conversionMultiplierSN 0.0E0 ;
qudt:hasDimensionVector qkdv:A0E0L1I0M0H0T1D0 ;
rdfs:isDefinedBy <http://qudt.org/$$QUDT_VERSION$$/vocab/unit> ;
rdfs:label "Random Meter Second"@en-US ;
rdfs:label "Random Metre Second" ;
rdfs:label "Random Metre Second"@en .

Rerun the build:

mvn spotless:apply; mvn install

Here's the output:

...lots of output...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Success! These two new units are now at least minimally comformant with the units ontology. They are still missing some triples that really ought to be there:

  • dcterms:description
  • qudt:applicableSystem
  • qudt:hasQuantityKind
  • qudt:informativeReference
  • qudt:symbol

Once you have filled in any additional triples and are getting no errors after rerunning the build, you have basically completed steps 1-8 of our GoodGitPractices. Carry on, starting at step 9.

⚠️ **GitHub.com Fallback** ⚠️