define a schema for relation members

[k-yle]

Closes #134

This is my proposal for a schema to define the roles of a relation. In summary:

• presets can have a new field called relation
• to avoid duplication, there is also relationCrossReference, similar to stringsCrossReference
• each role is defined with a default (en-US) label, just like presets & fields.

Example for type=boundary:

{
  "relation": {
    "allowDuplicateMembers": false,
    "members": [
      {
        "roles": { "inner": "Inner" },
        "geometry": ["line", "area"],
        "matchTags": [{}]
      },
      {
        "roles": { "outer": "Outer" },
        "geometry": ["line", "area"],
        "matchTags": [{}],
        "min": 1
      },
      {
        "roles": { "admin_centre": "Capital", "label": "Label" },
        "geometry": ["point", "vertex"],
        "matchTags": [{ "place": "*" }],
        "max": 1
      }
    ]
  }
}

Regarding matchTags:

• [{}] means any tags
• [] means no tags (it will never match, this is unhelpful)
• [{ a: 1, b: 2 }] means a=1 AND b=2
• [{ a: 1 }, { b: 2 }] means a=1 OR b=2

[1ec5]

Thanks!

[1ec5]

How useful is it to be able to combine multiple roles in the same role definition? Are there any relation types with lots of very similar roles that would have verbose definitions?

[k-yle]

PTv2's stop(_on_demand)?(_exit_only|_entry_only)? is probably the most verbose (likewise for platform_*). That would be 6 entries in a single JSON block.

So, there would be 13+ translatable strings for the PTv2 schema. I'm not sure how we could optimise this further

"members": [
 {}, // 6x stop_*                vertex
 {}, // 6x platform_*            line + area
 {}, // 1x (empty string)        line
 {}, // 0x (other)               any geometry
]

[1ec5]

Ah OK, that’s what I was missing – a case where a relation type has lots of very similar roles.

[1ec5]

Would it be useful to define something for documentation here too? It would be nice to be able to show a tooltip with a description of the role, for example to clarify that “Capital” (admin_centre) is a capital city, not a government headquarters building. The matchTags should prevent further mixups, but the user might encounter an already mistagged role and need to know the difference.

The wiki has a number of data items about roles, but none of them are tied to article titles. There’s a separate set of articles about roles under the “Role:” pseudonamespace, but these mostly serve as disambiguation pages, directing readers to the relation type pages.

We could set up more specific, per–relation type pages that have predictable titles and are linked to the data items. If so, then we wouldn’t necessarily need anything about documentation in the schema. Alternatively, we could add a property to the schema that indicates the QID of the data item about the role in the particular relation type.

[k-yle]

great question, I wasn't aware of these data items! It's a shame that we can't query the wikibase API by P21 permanent relation role ID

What approach do you think is better? I can see downsides of both methods:

• Creating wiki pages like Role:multipolygon=outer might confuse people because the syntax for P21 looks very similar to an OSM tag. Role:multipolygon/outer might be less confusing. I assume these pages would be stubs or redirect pages?
• Storing the QID for each role in this repository would be cumbersome and error-prone

[1ec5]

great question, I wasn't aware of these data items! It's a shame that we can't query the wikibase API by P21 permanent relation role ID

openstreetmap/operations#903 would install an extension that would allow us to easily query for data items by the value of a statement. In theory, you can already do so using Sophox, but whatever process ingests new data items into Sophox hasn’t been working for a while: Sophox/sophox#31.

I assume these pages would be stubs or redirect pages?

I was thinking of creating them as redirect pages for now, since there are already other pages that go into more detail, but in principle there could be full-fledged pages in the future.

Creating wiki pages like Role:multipolygon=outer might confuse people because the syntax for P21 looks very similar to an OSM tag.

Or maybe “Relation:multipolygon/outer”, assuming a relation type will never have a slash in it. Both this format and “Role:multipolygon/outer” carry the downside that, if the Translate extension is ever installed on the wiki (openstreetmap/operations#649), it’ll start using subpages for translations, with ISO language codes as subpage names. The to role will conflict with Tongan, maybe others too. Blank roles would also wind up with an awkward page title. Maybe something more verbose but less ambiguous like “Relation:multipolygon/Roles/outer” or “Role:outer (multipolygon)” would be more future-proof. We could ask the wiki community what they’d prefer.

[k-yle]

openstreetmap/operations#903 seems like the simplest solution to me, since it doesn't involve mass-creating wiki pages, nor inventing a new syntax for these pages' names.

The only thing we would need to store in this repository is the P41 for each relation. Then we can lookup the documentation for each role using the same approach as presets & fields.

I'm not very familiar with mediawiki, but we're running v1.39, so there's no major update required to install this extension?

[1ec5]

There aren’t any technical blockers as far as I know. But that request has been languishing for a while, so it might be quicker to just create the redirects on the wiki as a stopgap.

[DujaOSM]

For what it's worth, following a request on Talk:Wiki that cited this discussion, I added data item Descriptions for two dozen most common relation roles. Only a few are linked to Wiki articles proper (mostly unusable), such as Q22741 and a few I added are linked to redirects (such as Q22737 ).

[k-yle]

I've added a property called relation.id to the schema, which would store the P41 value, such as multipolygon. This will be needed regardless of how we query the wiki.

[...] We could ask the wiki community what they’d prefer.

It sounds like creating redirect or stub pages for each role isn't a popular idea.... Which means there's no way for iD to query this data without the WikibaseCirrusSearch extension.

[1ec5]

Using the new relation member roles (P54) property, the existing wbgetentities response now includes the QID of the item for each role pertaining to the relation type. We can get the ID and descriptions of each item in a separate wbgetentities call. This isn’t as streamlined as the redirect approach, but it should still be workable, since none of the relation types has more than a handful of itemized roles.

Alternatively, if we’re comfortable with relying on the apparent English label naming convention for these role items, we can issue a single wbsearchentities call in the form “type relation” to get the relation type item plus all the associated role items. However, this is inherently limited to getting the description in the user’s language; we wouldn’t be able to get any image or other metadata.

[1ec5]

I also just noticed that a bunch of the role items already have their sitelinks set to nonexistent pages like “Relation:boundary=admin centre”, as documented. This makes it possible to access these items directly using wbgetentities.

[k-yle]

in that case, I believe that https://github.com/ideditor/schema-builder/compare/5157ab..31f9af means that the schema now has all the information required to construct an API query for the documentation (?)