define a schema for relation members

Author: k-yle

README.md

@@ -386,6 +386,97 @@ For example,
 }
 ```
 
+##### `relation`
+
+For relations, this object describes which roles are allowed, which tags are required for each role, and other constraints related to relation roles.
+
+* `relation.id` – a string. This is the “permanent relation type ID”, it must match the value of [permanent relation type ID<sup><code>P41</code></sup>](https://osm.wiki/Property:P41) in the OSM wiki’s wikibase system.
+* `relation.allowDuplicateMembers` – a boolean. Set to `true` if the same OSM feature is allowed to appear multiple times in the relation's members.
+* `relation.optionalTags` – an object, only useful for specifying placeholders which are referenced in `members.*.matchTags`. See example below.
+* `relation.members` – an array of objects, which lists every relation role that is permitted as a member (see below).
+
+A full example looks like this:
+
+```jsonc
+// type/restriction/no_u_turn.json
+{
+  "relation": {
+    "id": "restriction", // the value of https://osm.wiki/Property:P41 from the matching
+    // item, in this case https://wiki.openstreetmap.org/wiki/Item:Q16054. Note that multiple
+    // relation entries may have the same `id` value.
+    "allowDuplicateMembers": true,
+    "members": [
+      {
+        "role": "from", // The relation role. An empty string is allowed.
+        "roleLabel": "From", // The label for the role, in the default language. An empty string is allowed.
+        "geometry": ["line"], // If not specified, any geometry is allowed.
+        "matchTags": [
+          // Describes which tags the member must have, if it has this role.
+          // `*` can be used as a tag value.
+          // If multiple array items are specified, only 1 needs to match.
+          // If this property is not specified, then any tags are allowed
+          { "highway": "*" },
+        ],
+        "min": 1, // The minimum number of times that this role must appear in the relation.
+        "max": 1, // The maximum number of times that this role must appear in the relation.
+      },
+      {
+        "role": "via",
+        "roleLabel": "Via",
+        "geometry": ["vertex", "line"],
+        "min": 1,
+      },
+      {
+        "role": "to",
+        "roleLabel": "To",
+        "geometry": ["line"],
+        "matchTags": [{ "highway": "*" }],
+        "min": 1,
+        "max": 1,
+      },
+    ],
+  },
+}
+```
+
+It is possible for the `matchTags` constraints to reference tags from the relation.
+
+For example, if a relation with [`type=route`](https://osm.wiki/Tag:type=route) + [`route=XXXX`](https://osm.wiki/Key:route) has a member with a role of `stop`, then that member must have a tag of `XXXX=yes`<sup>[[1]](https://osm.wiki/Relation:route#Members)</sup>. This can be expressed using the following syntax:
+
+```jsonc
+// type/route.json
+{
+  "relation": {
+    "optionalTags": {
+      "route": "$1", // 👈 the tag value can be referenced below using $1
+    },
+    "members": [
+      {
+        "role": "stop",
+        "roleLabel": "Stop Position",
+        "geometry": ["point", "vertex"],
+        "matchTags": [
+          {
+            "public_transport": "stop_position",
+            "$1": "yes", // 👈 the member must have $1=yes. $1 is determined
+            //                 by the value of route=* on the relation.
+          },
+        ],
+      },
+    ],
+  },
+}
+```
+
+##### `relationCrossReference`
+
+To avoid repeating the [`relation` object](#relation) in several presets, you can use `relationCrossReference` to reference another preset.
+
+For example:
+```js
+  "relationCrossReference": "{type/route}"
+```
+
 ### Fields
 
 Fields are reusable form elements that can be associated with presets.

lib/build.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import { styleText } from 'node:util';
 import fs from 'fs';
-import jsonschema from 'jsonschema';
+import { Validator } from 'jsonschema';
 import path from 'path';
 import shell from 'shelljs';
 import YAML from 'js-yaml';
@@ -22,6 +22,8 @@ const discardedSchema = require('../schemas/discarded.json');
 
 let _currBuild = null;
 
+const jsonschema = new Validator();
+
 function validateData(options) {
   const START = '🔬  ' + styleText('yellow', 'Validating schema...');
   const END = '👍  ' + styleText('green', 'schema okay');
@@ -205,6 +207,9 @@ function read(f) {
 
 
 function validateSchema(file, instance, schema) {
+  // add this schema to the cache, so $ref can be resolved faster
+  jsonschema.addSchema(schema);
+
   let validationErrors = jsonschema.validate(instance, schema).errors;
 
   if (validationErrors.length) {
@@ -366,6 +371,13 @@ function generatePresets(dataDir, tstrings, searchableFieldIDs, listReusedIcons)
       if (!icons[icon]) icons[icon] = [];
       icons[icon].push(id);
     }
+
+    if (preset.relation) {
+      tstrings.presets[id].relation_roles = {};
+      for (const member of preset.relation.members) {
+        tstrings.presets[id].relation_roles[member.role] = member.roleLabel;
+      }
+    }
   });
 
   if (listReusedIcons) {
@@ -465,8 +477,10 @@ function generateTranslations(fields, presets, tstrings, searchableFieldIDs) {
     let tags = preset.tags || {};
     let keys = Object.keys(tags);
 
+    const tagsString = keys.map(k => `${k}=${tags[k]}`).join(' + ');
+
     if (keys.length) {
-      yamlPreset['#name'] = keys.map(k => `${k}=${tags[k]}`).join(' + ');
+      yamlPreset['#name'] = tagsString;
       if (yamlPreset.aliases) {
         yamlPreset['#name'] += ' | ' + yamlPreset.aliases.split('\n').join(', ');
       }
@@ -477,6 +491,12 @@ function generateTranslations(fields, presets, tstrings, searchableFieldIDs) {
       yamlPreset['#name'] += ` | Local preset for countries ${preset.locationSet.include.map(country => `"${country.toUpperCase()}"`).join(', ')}`;
     }
 
+    if (yamlPreset.relation_roles) {
+      for (const role in yamlPreset.relation_roles) {
+        yamlPreset.relation_roles[`#${role}`] = `Relation role “${role}” when used with ${tagsString}`;
+      }
+    }
+
     if (preset.searchable !== false) {
       if (yamlPreset.terms) {
         yamlPreset['#terms'] = 'terms: ' + yamlPreset.terms;

schemas/field.json

@@ -97,8 +97,7 @@
             "minItems": 1,
             "uniqueItems": true,
             "items": {
-                "type": "string",
-                "enum": ["point", "vertex", "line", "area", "relation"]
+              "$ref": "#/$defs/Geometry"
             }
         },
         "default": {
@@ -382,5 +381,11 @@
                 { "required": ["keys"] }
             ]}
         ]}
-    ]
+    ],
+    "$defs": {
+        "Geometry": {
+            "type": "string",
+            "enum": ["point", "vertex", "line", "area", "relation"]
+        }
+    }
 }

schemas/preset.json

@@ -135,8 +135,91 @@
             },
             "minProperties": 1,
             "additionalProperties": false
+        },
+        "relation": {
+            "$ref": "#/$defs/RelationSchema"
+        },
+        "relationCrossReference": {
+            "description": "A preset can reference the relation schema from another preset, instead of defining the same schema again.",
+            "type": "string",
+            "pattern": "^\\{.+\\}$"
         }
     },
     "additionalProperties": false,
-    "required": ["name", "geometry", "tags"]
+    "required": ["name", "geometry", "tags"],
+    "$defs": {
+        "RelationSchema": {
+            "type": "object",
+            "properties": {
+                "optionalTags": {
+                    "type": "object",
+                    "description": "Only useful for specifying placeholders which are referenced in members.*.matchTags",
+                    "examples": [{ "route": "$1" }],
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "minProperties": 1
+                },
+                "id": {
+                    "type": "string",
+                    "description": "The “permanent relation type ID”, this should match the value of https://osm.wiki/Property:P41 in the OSM wiki’s wikibase system."
+                },
+                "allowDuplicateMembers": {
+                    "type": "boolean",
+                    "description": "Set to `true` if the same OSM feature is allowed to appear multiple times in the relation's members."
+                },
+                "members": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "role": {
+                                "type": "string",
+                                "description": "The relation role. An empty string is allowed."
+                            },
+                            "roleLabel": {
+                                "type": "string",
+                                "description": "The label for the role, in the default language. An empty string is allowed."
+                            },
+                            "geometry": {
+                                "type": "array",
+                                "uniqueItems": true,
+                                "items": {
+                                    "$ref": "field.json#/$defs/Geometry"
+                                },
+                                "description": "If not specified, any geometry is allowed"
+                            },
+                            "matchTags": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "additionalProperties": {
+                                        "type": "string"
+                                    },
+                                    "minProperties": 1
+                                },
+                                "examples": [
+                                    [{ "a": 1, "b": 2 }],
+                                    [{ "a": 1 }, { "b": 2 }]
+                                ],
+                                "description": "`*` can be used as a tag value. If multiple array items are specified, only 1 needs to match. If not specified, then any tags are allowed"
+                            },
+                            "min": {
+                                "type": "integer",
+                                "description": "If unspecified, there is no minimum"
+                            },
+                            "max": {
+                                "type": "integer",
+                                "description": "If unspecified, there is no maximum"
+                            }
+                        },
+                        "required": ["role", "roleLabel"],
+                        "additionalProperties": false
+                    }
+                }
+            },
+            "required": ["id", "allowDuplicateMembers", "members"],
+            "additionalProperties": false
+        }
+    }
 }