Revising ADAPT Standard's Unit Of Measures

[kelly-nelson]

Following discussions between members of AgGateway and QUDT, I'm creating an issue to discuss enhancing Units of Measure.

Use Cases

An ADAPT Standard consumer wishes to programmatically convert an ADAPT unit code into a UOM construct in a library in their chosen platform without hardcoding unit mappings in their code.

An ADAPT Standard consumer wants more than just the English name for a given unit code, either because they want to map to a different language, or they want richer information on what the unit means.

Current Processes

Currently the ADAPT Unit of Measure file maps only an english name of the unit, classified within the English name of the dimension. Without using the ADAPT Framework C# conversion code, users must create their own mappings of ADAPT codes to any unit of measure systems/converters used, as well as write parsing logic for the compound unit syntax. There is already divergence between the ADAPT Standard and Framework on units, and this will get larger.

QUDT, UCUM, and UN/CEFACT Req20 are formal catalogs of units that also have varying degrees of additional context (such as conversion factors).

QUDT and UCUM are supported by libraries in java, but otherwise none of these standards appear to have wide support in software. The problem of reading a unit code and constructing it into strongly typed unit of measure does not appear to be widely supported (if at all). The degree to which programming languages have widely-used libraries for units of measure, interoperability does not seem to be a common use case.

Proposed Object Model

Add a new unit mappings file alongside the existing ADAPT abbreviations file like the below. It would only include units of measure used in the Data Type Definitions

"unit_mappings": [ "kg1ha-1": [ "qudt": "http://qudt.org/vocab/unit/KiloGM-PER-HA", "ucum": "kg/[har]" ], ... ]

This may involve pull requests to QUDT for unsupported units (UCUM has a syntax to make compound units from simple units like ADAPT), and wouldn't do anything with UNCEFACT Req 20 for compound units.

[kelly-nelson]

Agreement in 19 November 2025 meeting to move past simply mapping and actively retire the ADAPT Unit of Measure codes in favor of QUDT URIs.

The impact to the schema will be limited to a single item dataTypeDefintion.numericDataTypeDefinitionAttributes.unitOfMeasureCode. We should rename to unitOfMeasureURI and update the definition to indicate that it should map to a QUDT URI.

[dubnemo]

@kelly-nelson @jim-wilson-kt
I SERIOUSLY recommend retaining the UOM code value in the payload AND use the 'cite your source' pattern; i.e., value and the source URI. This follows a lot of other standards approaches, including UN/CEFACT CCS, OAGi connectSpec, etc.

For example, a measurement payload could include"

{
"measure": "2.3433",
"uom": "M",
"uomSource": "https://qudt.org/vocab/unit/M"
}

The last nit picky thing is that I do not agree in the choosen URI. For this to be proper, it should point to a JSON or JSON-LD file, but it looks like the TopBraid server is not publicly available, or there are other issues.

I suggest that the URI navigate directly to unit JSON property show below, or the top level, and be machine-processible (not HTML that is).

[kelly-nelson]

@dubnemo The URI/JSON-LD best practice is really for the QUDT project vs. ADAPT. For our purposes, there is a URI with a discrete meaning.

Perhaps the unit change in ADAPT is the right moment to think about enriching the ADAPT format to JSON-LD. Rather than the full URI at every relevant node in the data, this:

"@context": {
    "unit": {
      "@id": "https://qudt.org/vocab/unit/"
    }
  } 

...

{
 "measure": 2.3433,
 "unit": "M"
}

In the past we might have done something like {"qudt-uom-code": "M"}, but there should be no harm in starting to enrich things with formal URIs and external schema mappings.