hydroserver2 · kjlippold · Aug 27, 2026 · Aug 11, 2026 · Aug 11, 2026 · Aug 25, 2026
diff --git a/apps/data-management/e2e/specs/metadata.spec.ts b/apps/data-management/e2e/specs/metadata.spec.ts
@@ -218,7 +218,7 @@ test.describe('metadata management', () => {
 
     await fillCombobox(page, 'Variable Type *', 'E2E Variable Type')
     await page
-      .getByLabel('Definition *')
+      .getByLabel('Definition')
       .fill('https://www.example.com/e2e-observed-property')
     await page
       .getByLabel('Description *')
@@ -268,8 +268,14 @@ test.describe('metadata management', () => {
       .getByRole('button', { name: /Add new processing level/i })
       .click()
 
+    await page.getByLabel('Name *').fill('E2E Processing Level')
     await page.getByLabel('Code *').fill(levelCode)
-    await page.getByLabel('Definition').fill('E2E processing level definition')
+    await page
+      .getByLabel('Description *')
+      .fill('E2E processing level description')
+    await page
+      .getByLabel('Definition')
+      .fill('https://example.com/processing-levels/e2e')
     await page.getByRole('button', { name: 'Save' }).click()
 
     const levelRow = page.locator('tr').filter({ hasText: levelCode }).first()
@@ -311,7 +317,9 @@ test.describe('metadata management', () => {
 
     await fillCombobox(page, 'Unit Type *', 'E2E Unit Type')
     await page.getByLabel('Symbol *').fill(`e2e${stamp}`)
-    await page.getByLabel('Definition *').fill('E2E unit definition')
+    await page
+      .getByLabel('Definition')
+      .fill(`https://example.com/units/e2e-${stamp}`)
     await page.getByLabel('Name *').fill(unitName)
     await page.getByRole('button', { name: 'Save' }).click()
 

diff --git a/apps/data-management/src/components/Datastream/DatastreamForm.vue b/apps/data-management/src/components/Datastream/DatastreamForm.vue
@@ -330,12 +330,15 @@
                   </template>
 
                   <InfoCard
-                    :title="item.definition"
+                    :title="item.name"
                     :subtitle="{
                       label: 'Code',
                       value: item.code,
                     }"
-                    :items="[{ label: 'Explanation', value: item.explanation }]"
+                    :items="[
+                      { label: 'Description', value: item.description },
+                      { label: 'Definition', value: item.definition },
+                    ]"
                     :isWorkspace="!!item.workspaceId"
                   />
                 </v-tooltip>

diff --git a/apps/data-management/src/components/Datastream/DatastreamInformationPanels.vue b/apps/data-management/src/components/Datastream/DatastreamInformationPanels.vue
@@ -238,9 +238,10 @@ onMounted(async () => {
 
   const pl = d.processingLevel
   processingLevelItems.value = [
+    { label: 'Name', value: pl.name },
     { label: 'Code', value: pl.code },
+    { label: 'Description', value: pl.description },
     { label: 'Definition', value: pl.definition },
-    { label: 'Explanation', value: pl.explanation },
   ]
 })
 </script>

diff --git a/apps/data-management/src/components/Datastream/DatastreamOverviewCard.vue b/apps/data-management/src/components/Datastream/DatastreamOverviewCard.vue
@@ -12,7 +12,7 @@
       <!-- Processing Level -->
       <div class="mb-3">
         <div class="text-subtitle-1 font-weight-medium">
-          {{ datastream.processingLevel.definition }}
+          {{ datastream.processingLevel.name }}
         </div>
         <div class="text-caption text-grey-darken-1">Processing Level</div>
       </div>

diff --git a/apps/data-management/src/components/Datastream/DatastreamSelectorCard.vue b/apps/data-management/src/components/Datastream/DatastreamSelectorCard.vue
@@ -190,7 +190,7 @@ const headers = [
   { title: 'ID', key: 'id' },
   { title: 'Name', key: 'name' },
   { title: 'Observed property', key: 'observedPropertyName' },
-  { title: 'Processing level', key: 'processingLevelDefinition' },
+  { title: 'Processing level', key: 'processingLevelName' },
   { title: 'Description', key: 'description', sortable: false },
   { title: 'Observation type', key: 'observationType' },
 
@@ -241,7 +241,7 @@ const tableItems = computed(() =>
     ...ds,
     observedPropertyName: ds.observedProperty?.name,
     methodName: ds.method.name,
-    processingLevelDefinition: ds.processingLevel.definition,
+    processingLevelName: ds.processingLevel.name,
     unit: ds.unit.name,
     phenomenonBeginTime: formatTime(ds.phenomenonBeginTime),
     phenomenonEndTime: formatTime(ds.phenomenonEndTime),

diff --git a/apps/data-management/src/components/Datastream/DatastreamTable.vue b/apps/data-management/src/components/Datastream/DatastreamTable.vue
@@ -1274,7 +1274,7 @@ const visibleDatastreams = computed(() => {
         ...d,
         OPName: op ? `${op.name} (${op.code})` : '',
         processingLevelCode: pl?.code ?? '',
-        processingLevelName: pl?.definition ?? '',
+        processingLevelName: pl?.name ?? '',
         methodName: method?.name ?? '',
         unitName: unit?.name ?? '',
         searchText: ',',

diff --git a/apps/data-management/src/components/Metadata/ObservedPropertyFormCard.vue b/apps/data-management/src/components/Metadata/ObservedPropertyFormCard.vue
@@ -23,11 +23,11 @@
           class="pb-4"
         />
 
-        <v-textarea
+        <v-text-field
           v-model="item.definition"
-          label="Definition *"
-          :rules="rules.requiredDescription"
-        ></v-textarea>
+          label="Definition"
+          :rules="item.definition ? rules.urlFormat : []"
+        />
 
         <v-textarea
           v-model="item.description"
@@ -90,8 +90,8 @@ const vocabularyStore = useVocabularyStore()
 const handleNameUpdated = () => {
   const name = item.value.name
   if (name && OPNames.includes(name)) {
-    item.value.definition = OPNameTypes[name].definition
-    item.value.description = OPNameTypes[name].description
+    item.value.definition = ''
+    item.value.description = `${OPNameTypes[name].definition}. ${OPNameTypes[name].description}`
   }
 }
 

diff --git a/apps/data-management/src/components/Metadata/ProcessingLevelFormCard.vue b/apps/data-management/src/components/Metadata/ProcessingLevelFormCard.vue
@@ -14,22 +14,28 @@
       validate-on="blur"
     >
       <v-card-text>
+        <v-text-field
+          v-model="item.name"
+          label="Name *"
+          :rules="rules.requiredAndMaxLength255"
+        />
+
         <v-text-field
           v-model="item.code"
           label="Code *"
           :rules="rules.requiredCode"
         />
 
         <v-textarea
-          v-model="item.definition"
-          label="Definition"
-          :rules="rules.maxLength(2000)"
+          v-model="item.description"
+          label="Description *"
+          :rules="rules.requiredDescription"
         />
 
-        <v-textarea
-          v-model="item.explanation"
-          label="Explanation"
-          :rules="rules.maxLength(2000)"
+        <v-text-field
+          v-model="item.definition"
+          label="Definition"
+          :rules="item.definition ? rules.urlFormat : []"
         />
 
         <v-card-actions>

diff --git a/apps/data-management/src/components/Metadata/ProcessingLevelTable.vue b/apps/data-management/src/components/Metadata/ProcessingLevelTable.vue
@@ -102,9 +102,10 @@ const ProcLevelHeaders = computed(() => {
     sortable?: boolean
     align?: 'end'
   }[] = [
+    { title: 'Name', key: 'name' },
     { title: 'Code', key: 'code' },
+    { title: 'Description', key: 'description' },
     { title: 'Definition', key: 'definition' },
-    { title: 'Explanation', key: 'explanation' },
   ]
   if (props.scope === 'all')
     base.push({ title: 'Scope', key: 'scope', sortable: false })
@@ -113,6 +114,6 @@ const ProcLevelHeaders = computed(() => {
 })
 
 const sortedItems = computed(() =>
-  items.value.sort((a, b) => a.code.localeCompare(b.code))
+  items.value.sort((a, b) => a.name.localeCompare(b.name))
 )
 </script>
diff --git a/apps/data-management/src/components/Metadata/UnitFormCard.vue b/apps/data-management/src/components/Metadata/UnitFormCard.vue
@@ -24,8 +24,8 @@
         />
         <v-text-field
           v-model="item.definition"
-          label="Definition *"
-          :rules="rules.requiredDescription"
+          label="Definition"
+          :rules="item.definition ? rules.urlFormat : []"
         />
         <v-text-field
           v-model="item.type"

diff --git a/apps/data-management/src/components/Orchestration/shared/DatastreamCardSelector.vue b/apps/data-management/src/components/Orchestration/shared/DatastreamCardSelector.vue
@@ -101,7 +101,7 @@ function searchText(datastream: Datastream): string {
     ds.observedProperty?.name,
     ds.observedProperty?.code,
     ds.processingLevel?.code,
-    ds.processingLevel?.definition,
+    ds.processingLevel?.name,
     ds.unit?.name,
     ds.unit?.symbol,
     ds.method?.name,

diff --git a/apps/data-management/src/components/Orchestration/shared/DatastreamResultCard.vue b/apps/data-management/src/components/Orchestration/shared/DatastreamResultCard.vue
@@ -42,7 +42,7 @@ function relatedValue(relation: string, key: string): string {
 function processingLevel() {
   const pl = (props.datastream as Datastream & Record<string, any>).processingLevel
   if (!pl) return props.datastream.processingLevelId || '-'
-  return [pl.code, pl.definition].filter(Boolean).join(' - ') || '-'
+  return [pl.code, pl.name].filter(Boolean).join(' - ') || '-'
 }
 
 function unit() {

diff --git a/apps/data-management/src/components/VisualizeData/DataVisDatasetsTable.vue b/apps/data-management/src/components/VisualizeData/DataVisDatasetsTable.vue
@@ -163,7 +163,7 @@
                 <span class="text-xs uppercase tracking-[0.04em] text-black/55"
                   >Processing level</span
                 >
-                <span>{{ item.qualityControlLevelDefinition || '—' }}</span>
+                <span>{{ item.processingLevelName || '—' }}</span>
               </div>
               <div class="flex flex-col gap-0.5 pt-1.5">
                 <span class="text-xs uppercase tracking-[0.04em] text-black/55"
@@ -335,7 +335,7 @@ const tableItems = computed(() => {
       ...ds,
       siteCodeName: monitoringSite?.code,
       observedPropertyName: observedPropertyDisplay,
-      qualityControlLevelDefinition: processingLevel?.definition,
+      processingLevelName: processingLevel?.name,
     }
   })
 })
@@ -359,7 +359,7 @@ const selectableHeaders = computed(() => {
 const sortBy = [
   { key: 'siteCodeName' },
   { key: 'observedPropertyName' },
-  { key: 'qualityControlLevelDefinition' },
+  { key: 'processingLevelName' },
 ]
 const selectedHeaders = computed({
   get: () =>

diff --git a/apps/data-management/src/components/VisualizeData/DataVisFiltersDrawer.vue b/apps/data-management/src/components/VisualizeData/DataVisFiltersDrawer.vue
@@ -247,7 +247,7 @@ const totalObservedPropertyNamesCount = computed(() => {
 const totalProcessingLevelNamesCount = computed(() => {
   const names = new Set<string>()
   processingLevels.value.forEach((pl) => {
-    if (pl.definition) names.add(pl.definition)
+    if (pl.name) names.add(pl.name)
   })
   return names.size
 })
@@ -287,11 +287,11 @@ const sortedProcessingLevelNames = computed(() => {
       return
     }
 
-    const definition = dataVisStore.processingLevelById.get(
+    const name = dataVisStore.processingLevelById.get(
       ds.processingLevelId
-    )?.definition
-    if (definition) {
-      names.add(definition)
+    )?.name
+    if (name) {
+      names.add(name)
     }
   })
 

diff --git a/apps/data-management/src/composables/useMetadata.ts b/apps/data-management/src/composables/useMetadata.ts
@@ -38,7 +38,7 @@ export function useMetadata(localWorkspace?: Ref<Workspace | undefined>) {
   const formattedProcessingLevels = computed(() =>
     processingLevels.value.map((pl) => ({
       ...pl,
-      title: `${pl.code}: ${pl.definition}`,
+      title: `${pl.code}: ${pl.name}`,
     }))
   )
 

diff --git a/apps/data-management/src/store/dataVisualization.ts b/apps/data-management/src/store/dataVisualization.ts
@@ -59,7 +59,7 @@ export const useDataVisStore = defineStore('dataVisualization', () => {
     },
     {
       title: 'Processing Level',
-      key: 'qualityControlLevelDefinition',
+      key: 'processingLevelName',
       visible: true,
     },
     {
@@ -154,7 +154,7 @@ export const useDataVisStore = defineStore('dataVisualization', () => {
 
     const PLName = processingLevelById.value.get(
       datastream.processingLevelId
-    )?.definition
+    )?.name
     return (
       PLName !== undefined && selectedProcessingLevelNameSet.value.has(PLName)
     )

diff --git a/apps/docs/docs/developing-and-contributing/how-to/using-the-typescript-client.md b/apps/docs/docs/developing-and-contributing/how-to/using-the-typescript-client.md
@@ -321,7 +321,8 @@ import { ObservedProperty } from "@hydroserver/client";
 const observedProperty = new ObservedProperty();
 observedProperty.workspaceId = "00000000-0000-0000-0000-000000000000";
 observedProperty.name = "Temperature";
-observedProperty.definition = "Air temperature";
+observedProperty.definition =
+  "http://vocabulary.odm2.org/variablename/airTemperature/";
 observedProperty.description = "Near-surface air temperature";
 observedProperty.type = "Climate";
 observedProperty.code = "AirTemp";
@@ -350,7 +351,7 @@ const unit = new Unit();
 unit.workspaceId = "00000000-0000-0000-0000-000000000000";
 unit.name = "Degree Celsius";
 unit.symbol = "C";
-unit.definition = "Degree Celsius";
+unit.definition = "https://qudt.org/vocab/unit/DEG_C";
 unit.type = "Temperature";
 
 const created = await hs.units.createItem(unit);
@@ -407,8 +408,8 @@ import { ProcessingLevel } from "@hydroserver/client";
 const processingLevel = new ProcessingLevel();
 processingLevel.workspaceId = "00000000-0000-0000-0000-000000000000";
 processingLevel.code = "0";
-processingLevel.definition = "Raw";
-processingLevel.explanation =
+processingLevel.name = "Raw";
+processingLevel.description =
   "Data have not been processed or quality controlled.";
 
 const created = await hs.processingLevels.createItem(processingLevel);

diff --git a/apps/docs/docs/introduction/key-concepts/datastreams.md b/apps/docs/docs/introduction/key-concepts/datastreams.md
@@ -23,17 +23,17 @@ In HydroServer, we describe datastream metadata in two groups:
 
 Below is a brief definition of each available linked metadata group a datastream can be linked to:
 
-**- Unit** refers to the measurement units of the data (like liters, meters, etc.). Each unit has a name, description, symbol (like 'C' for degrees celsius), and type. Units for HydroServer are derived from 
+**- Unit** refers to the measurement units of the data (like liters, meters, etc.). Each unit has a name, symbol (like 'C' for degrees Celsius), type, and optional external definition URI. Units for HydroServer are derived from
 [ODM2's Units controlled vocabularies list for Units](http://vocabulary.odm2.org/units/).
 
-**- Processing Level** indicates the degree of processing or analysis that the data within that datastream has undergone, which includes a code, definition, and explanation. Users are free to use their own conventions, but a new HydroServer instance provides the following defaults that can be loaded from templates like the other linked metadata:
+**- Processing Level** indicates the degree of processing or analysis that the data within that datastream has undergone, which includes a code, name, description, and optional external definition URI. Users are free to use their own conventions, but a new HydroServer instance provides the following defaults that can be loaded from templates like the other linked metadata:
 
-- 0: Raw data
+- 0: Raw
 - 1: Quality controlled data
 - 2: Derived products
 - 3: Interpreted products
 - 4: Knowledge products
-- 9999: Unknown
+- -9999: Unknown
 
 **- Observed Property** is the specific characteristic or attribute being observed, like temperature or flow rate. As with Units, we have adopted
 [ODM2's Observed Property controlled vocabularies list](http://vocabulary.odm2.org/variablename/).

diff --git a/apps/docs/docs/references/data-dictionary.md b/apps/docs/docs/references/data-dictionary.md
@@ -65,9 +65,9 @@ An ObservedProperty specifies the phenomenon of an Observation, such as flow, te
 | M        | id                     | A primary key unique identifier for the ObservedProperty.                                                                          | UUID      |
 | O        | workspace_id           | A foreign key identifier for the Workspace that owns the ObservedProperty. If omitted, the ObservedProperty is shared system-wide. | UUID      |
 | M        | name                   | A descriptive name for the ObservedProperty.                                                                                       | String    |
-| M        | definition             | A text definition of the ObservedProperty or a URL pointing to a controlled definition.                                            | Text      |
+| O        | definition             | A URI pointing to an externally controlled definition of the ObservedProperty.                                                     | URI       |
 | M        | description            | A text description of the ObservedProperty.                                                                                        | Text      |
-| M        | observed_property_type | The type of ObservedProperty.                                                                                                      | String    |
+| M        | type                   | The type of ObservedProperty.                                                                                                      | String    |
 | M        | code                   | A brief text code identifying the ObservedProperty.                                                                                | String    |
 
 ## Organization
@@ -119,8 +119,9 @@ The degree of quality control or processing to which a Datastream has been subje
 | M        | id           | A primary key unique identifier for the ProcessingLevel.                                                                         | UUID      |
 | O        | workspace_id | A foreign key identifier for the Workspace that owns the ProcessingLevel. If omitted, the ProcessingLevel is shared system-wide. | UUID      |
 | M        | code         | A brief text code identifying the ProcessingLevel.                                                                               | String    |
-| O        | definition   | A text definition of the ProcessingLevel.                                                                                        | Text      |
-| O        | explanation  | A longer text explanation of the ProcessingLevel.                                                                                | Text      |
+| M        | name         | A descriptive name for the ProcessingLevel.                                                                                      | String    |
+| M        | description  | A text description of the ProcessingLevel.                                                                                       | Text      |
+| O        | definition   | A URI pointing to an externally controlled definition of the ProcessingLevel.                                                    | URI       |
 
 ## ResultQualifier
 
@@ -194,8 +195,8 @@ The unit of measure associated with the Observations within a Datastream.
 | O        | workspace_id | A foreign key identifier for the Workspace that owns the Unit. If omitted, the Unit is shared system-wide. | UUID      |
 | M        | name         | A descriptive name for the Unit.                                                                           | String    |
 | M        | symbol       | An abbreviation or symbol used for the Unit.                                                               | String    |
-| M        | definition   | A URL or text definition for the Unit.                                                                     | Text      |
-| M        | unit_type    | The type of Unit.                                                                                          | String    |
+| O        | definition   | A URI pointing to an externally controlled definition of the Unit.                                       | URI       |
+| M        | type         | The type of Unit.                                                                                          | String    |
 
 ## Workspace