new approach: define units in a separate file

Author: k-yle

README.md

@@ -148,6 +148,7 @@ data/
     defaults.json
     deprecated.json
     discarded.json
+    units.json
 ```
 
 The format for each file is defined in the [`schemas`](schemas) directory.
@@ -748,30 +749,27 @@ Used when `type = measurement`. Defines the unit of measurements that are suppor
   "key": "diameter",
   "type": "measurement",
   "measurement": {
-     // The dimension being measured. This constrains the permitted units.
-     // The ID id defined by CLDR.
+    // The dimension being measured. This constrains the permitted units.
+    // The ID id defined by CLDR.
     "dimension": "length",
 
-    "units": {
-      // The key defines the ID of the of the unit, as defined by CLDR.
-      // The values define the suffix used in the OSM tag value. 
-      // If there are multiple values in the array (such as "kW", "KW"),
-      // then the first one is the preferred value, but iD will still 
-      // recognise the alternative/s.
-      "meter": ["m"],
-      "centimeter": ["cm"],
-      "yard": ["yd"],
-
-      // mm is the default unit in OSM, so the tag value should have no suffix.
-      // Therefore, the first array item is blank.
-      // The second value exists so that iD will recognise tag values with an 
-      // explicit 'mm' suffix.
-      "millimeter": ["", "mm"]
-    }
+    // The corresponding 'usage' from CLDR.
+    "usage": "default",
+
+    // If the field only allows some units, you can list them here
+    // using CLDR's unit names. If not specified, then, all units from
+    // this dimension are allowed.
+    "units": ["meter", "centimeter", "foot-and-inch"],
+
+    // Some OSM tags have a default unit, which does not need to be explicitly included in the tag value.
+    // This field defines how to interpret a unit-less value:
+    "impliedUnit": "meter"
   }
 }
 ```
 
+To convert the unit IDs into the values used by OSM, see [§Units](#Units).
+
 Translations for the [`narrow` and `long` form](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) of each unit are bundled into iD-tagging-schema's locale files.
 
 ### Deprecations
@@ -808,6 +806,26 @@ To update a specific tag to a specific new tag
   },
 ```
 
+## Units
+
+The [`units.json` file](https://github.com/openstreetmap/id-tagging-schema/blob/main/data/units.json) defines the suffix which is used in the OSM tag value for every unit of measurement.
+
+```jsonc
+{
+  "power": {
+    // The key defines the ID of the of the unit, as defined by CLDR.
+    // The values define the suffix used in the OSM tag value.
+    "megawatt": ["MW"],
+
+    // If there are multiple values in the array, then the first one
+    // is the preferred value, but iD will still recognise the alternative/s.
+    "kilowatt": ["kW", "KW"],
+
+    // `horsepower` is not included, therefore it can't be used by any fields.
+  },
+}
+```
+
 ## Contributing
 
 iD's [code of conduct](https://github.com/openstreetmap/iD/blob/release/CODE_OF_CONDUCT.md) and

lib/build.js

@@ -19,6 +19,7 @@ const categorySchema = require('../schemas/preset_category.json');
 const defaultsSchema = require('../schemas/preset_defaults.json');
 const deprecatedSchema = require('../schemas/deprecated.json');
 const discardedSchema = require('../schemas/discarded.json');
+const unitsSchema = require('../schemas/generated/units.json');
 
 /** @import { TranslationOptions } from "./translations.js" */
 
@@ -142,6 +143,11 @@ function processData(options, type) {
     validateSchema(dataDir + '/discarded.json', discarded, discardedSchema);
   }
 
+  const units = read(dataDir + '/units.json');
+  if (units) {
+    validateSchema(dataDir + '/units.json', units, unitsSchema);
+  }
+
   let categories = generateCategories(dataDir, tstrings);
   if (options.processCategories) options.processCategories(categories);
 
@@ -204,6 +210,7 @@ function processData(options, type) {
   if (defaults) fs.writeFileSync(distDir + '/preset_defaults.json', JSON.stringify(defaults, null, 4));
   if (deprecated) fs.writeFileSync(distDir + '/deprecated.json', JSON.stringify(deprecated, null, 4));
   if (discarded) fs.writeFileSync(distDir + '/discarded.json', JSON.stringify(discarded, null, 4));
+  if (units) fs.writeFileSync(distDir + '/units.json', JSON.stringify(units, null, 4));
 
   expandTStrings(tstrings);
   let translationsForJson = {};
@@ -221,6 +228,7 @@ function processData(options, type) {
     minifyJSON(distDir + '/preset_defaults.json', distDir + '/preset_defaults.min.json'),
     minifyJSON(distDir + '/deprecated.json', distDir + '/deprecated.min.json'),
     minifyJSON(distDir + '/discarded.json', distDir + '/discarded.min.json'),
+    minifyJSON(distDir + '/units.json', distDir + '/units.min.json'),
     minifyJSON(distDir + '/translations/' + sourceLocale + '.json', distDir + '/translations/' + sourceLocale + '.min.json'),
     generateTypeDefs(distDir),
   ];

schemas/field.json

@@ -378,24 +378,25 @@
                     "description": "The corresponding 'usage' from CLDR"
                 },
                 "units": {
-                    "type": "object",
-                    "description": "Defines the permitted units. The key is the ID used by CLDR (see https://cdn.jsdelivr.net/npm/cldr-core/supplemental/unitPreferenceData.json). The value is the value used in the OSM tag. If there are multiple values, the first one will be preferred. Use an empty string if the unit is not included in the OSM tag.",
-                    "additionalProperties": {
-                      "type": "array",
-                      "items": {
-                        "type": ["string", "null"]
-                      },
-                      "minItems": 1
-                    },
-                    "minProperties": 1
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "Optional, if only some units are allowed for this tag, then list the permitted units here, using the unit IDs from CLDR (see https://cdn.jsdelivr.net/npm/cldr-core/supplemental/unitPreferenceData.json).",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "impliedUnit": {
+                    "type": "string",
+                    "description": "Some OSM tags have a default unit, which does not need to be explicitly included in the tag value. This field defines how to interpret a unit-less value."
                 }
             },
             "allOf": [
                 { "$ref": "./generated/usage.json" },
-                { "$ref": "./generated/units.json" }
+                { "$ref": "./generated/unit-types.json" }
             ],
-            "additionalItems": false,
-            "required": ["dimension", "usage", "units"]
+            "additionalProperties": false,
+            "required": ["dimension", "usage"]
         }
     },
     "additionalProperties": false,

scripts/build-schema.js

@@ -37,61 +37,86 @@ const usage = {
   }),
 };
 
-const units = {
+const unitTypes = {
   $schema: 'http://json-schema.org/draft-07/schema#',
   $id: 'https://cdn.jsdelivr.net/npm/@ideditor/schema-builder/schemas/generated/units.json',
 
-  allOf: dimension.enum.map((dimension) => {
-    const defaults =
-      unitPreference.supplemental.unitPreferenceData[dimension] || {};
+  $defs: Object.fromEntries(
+    dimension.enum.map((dimension) => {
+      const defaults =
+        unitPreference.supplemental.unitPreferenceData[dimension] || {};
 
-    /** @type {import('json-schema').JSONSchema4['properties']} */
-    const properties = {};
+      /** @type {Set<string>} */
+      const units = new Set(
+        // units.json does not include 'Mixed Units', so we need to add some of
+        // the 'Mixed Units' (only the ones which are used):
+        Object.values(defaults)
+          .flatMap(Object.values)
+          .flat()
+          .map((item) => item.unit),
+      );
 
-    for (const key in unitTranslations.main.en.units.long) {
-      if (key.startsWith(`${dimension}-`)) {
-        const unit = key.split('-').slice(1).join('-');
-        properties[unit] = {
-          type: 'array',
-          items: { type: 'string' },
-          minItems: 1,
-        };
+      // also add all standard units:
+      for (const key in unitTranslations.main.en.units.long) {
+        if (key.startsWith(`${dimension}-`)) {
+          const unit = key.split('-').slice(1).join('-');
+          units.add(unit);
+        }
       }
-    }
-
-    // units.json does not include 'Mixed Units', so we need to add some of
-    // the 'Mixed Units' (only the ones which are used).
-    const mixedUnits = new Set(
-      Object.values(defaults)
-        .flatMap(Object.values)
-        .flat()
-        .map((item) => item.unit),
-    );
 
-    for (const unit of mixedUnits) {
-      properties[unit] ||= {
-        type: 'array',
-        items: { type: 'null' },
-        minItems: 1,
-        maxItems: 1,
-      };
-    }
+      return [dimension, { enum: [...units] }];
+    }),
+  ),
 
+  allOf: dimension.enum.map((dimension) => {
     return {
       if: { properties: { dimension: { const: dimension } } },
       then: {
         properties: {
-          units: {
-            additionalProperties: false,
-            properties,
-          },
+          units: { items: { $ref: `#/$defs/${dimension}` } },
+          impliedUnit: { $ref: `#/$defs/${dimension}` },
         },
       },
     };
   }),
 };
 
-const files = { dimension, usage, units };
+const units = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://cdn.jsdelivr.net/npm/@ideditor/schema-builder/schemas/generated/units.json',
+  title: 'Units of measurement',
+  description:
+    'Defines the suffix used in the OSM tag value for every unit of measurement. If there are multiple values, the first one will be preferred.',
+  type: 'object',
+  properties: Object.fromEntries(
+    Object.entries(unitTypes.$defs).map(([dimension, value]) => {
+      return [
+        dimension,
+        {
+          type: 'object',
+          properties: Object.fromEntries(
+            value.enum.map((unit) => {
+              return [
+                unit,
+                {
+                  type: 'array',
+                  minItems: 1,
+                  uniqueItems: true,
+                  items: { type: 'string' },
+                },
+              ];
+            }),
+          ),
+          additionalProperties: false,
+          minProperties: 1,
+        },
+      ];
+    }),
+  ),
+  additionalProperties: false,
+};
+
+const files = { dimension, usage, 'unit-types': unitTypes, units };
 
 const generatedFolder = join(import.meta.dirname, '../schemas/generated');
 await fs.mkdir(generatedFolder, { recursive: true });