Proposal:Documentation of key prefixes & suffixes

From OpenStreetMap Wiki
Jump to navigation Jump to search
Documentation of key prefixes & suffixes
Proposal status: Approved (active)
Proposed by: Push-f
Draft started: 2022-06-28
RFC start: 2022-06-28
Vote start: 2022-07-24
Vote end: 2022-08-07

Proposal

The wiki currently documents tag keys on Key: pages and tag values on Tag: pages.

Key prefixes are currently documented sometimes on pages named Key:prefix and sometimes on pages named Key:prefix:. See for example Key:addr and Key:disused:

Let us instead establish the convention of documenting key prefixes at pages named Key:prefix:* and key suffixes at pages named Key:*:suffix.

Note that key prefixes/suffixes do not have to be documented on such pages, e.g. *:conditional=* is documented at Conditional restrictions. However in such cases a redirect (e.g. Key:*:conditional) should be created to the respective page to improve discoverability as well as to ensure linkability with the {{Prefix}} & {{Suffix}} templates (as well as from data items).

The data items of key prefixes & key suffixes currently wrongly have the property "instance of" = "key". To distinguish keys from key prefixes/suffixes we create two new data items to be used for "instance of" (one labeled "key prefix" and one labeled "key suffix"). Analogous to the permanent key ID property we create two properties (one labeled "permanent key prefix ID" and one labeled "permanent key suffix ID"). To prevent humans from confusing data items describing keys and data items describing key prefixes/suffixes, the latter should be labeled with trailing/leading colons.

Rationale

The current practice of documenting key prefixes on pages with names indistinguishable from pages used to describe keys is confusing for both human wiki readers as well as projects that parse the wiki pages such as taginfo.

While any key prefix can also be used as a key, doing so is often discouraged, e.g:

  • using addr:*=* is encouraged, while using addr=* is discouraged
  • using contact:*=* is encouraged, while using contact=* is discouraged
  • but there are also cases where using both is encouraged, e.g. lanes:*=* and lanes=*

It is therefore important to make a clear distinction between key prefixes and keys. Introducing a clear page naming convention helps accomplish that. For example: Key:addr:* could make use of the {{KeyPrefixDescription}} template with |status=de facto, while Key:addr could make use of the {{KeyDescription}} template with |status=deprecated.

The following alternatives have been considered:

Page name Reason(s) against
Key:prefix indistinguishable from regular keys and thus highly confusing
Key:prefix:
  • The colon is very easy to miss, adding an additional * makes the distinction more obvious.
  • Does not work well for key suffixes because e.g. Key::conditional would be very confusing.
KeyPrefix:prefix
  • you cannot navigate to subkeys by just editing the very end of the URL
  • the page about e.g. the addr:*=* prefix would not show up in the search autocompletion when searching for "Key:addr"
    (even if Key:prefix redirected to KeyPrefix:prefix because CirrusSearch gives redirects a lower search result weight)

Key suffixes may be combined e.g. name=* + *:left=* + *:en=* = name:left:en=*. Note that the order in which key suffixes are combined matters (and we should strive to document such conventions on the wiki). This proposal does not establish a documentation convention for key infixes because in the current tagging conventions they (sensibly) appear to share the semantics of same-named suffixes (e.g. while adding the *:en=* suffix to name:left=* technically turns the *:left=* suffix into an infix it does not change the semantics of *:left=*).

Features/Pages affected

The data items of these pages will be updated accordingly.

External discussions

Comments

Please comment on the discussion page.

Voting

Voting closed

Voting on this proposal has been closed.

It was approved with 11 votes for, 1 vote against and 0 abstentions.

  • I approve this proposal I approve this proposal. As proposing contributor. --Push-f (talk) 07:33, 24 July 2022 (UTC)
  • I approve this proposal I approve this proposal. But I would rather move to Prefix:disused:* or KeyPrefix:disused:* - "editing the very end of the URL" is extremely niche activity and autocompletion issue can be solved by having a clear link on top of say Key:addr Also, different prefix could help to reduce confusion by taginfo and other similar tools. Still, I had plan to do this on my TODO list for years, I will not nitpick when someone is solving issue in 80% rather 100% --Mateusz Konieczny (talk) 08:52, 24 July 2022 (UTC)
"Note that the order in which key suffixes are combined matters (and we should strive to document such conventions on the wiki)" - Order of key parts exists Mateusz Konieczny (talk) 08:57, 24 July 2022 (UTC)
The autocompletion issue with such namespaces is that the page about the prefix would not show up when searching for e.g. "Key:addr", adding a link to Key:addr does not solve the issue ... it's just a workaround that requires one more click. I think the prefix pages should show up immediately (you shouldn't have to navigate to them via an intermediary page). --Push-f (talk) 14:38, 24 July 2022 (UTC)
  • I approve this proposal I approve this proposal. Essential to me is the fact that finally there is a distinction from keys at all. {{KeyPrefixDescription}} and {{Prefix}}/{{Suffix}} gonna be good to have. It would be nice if taginfo would be enhanced for prefixes and suffixes, too. --Chris2map (talk) 10:08, 24 July 2022 (UTC)
  • I approve this proposal I approve this proposal. --Popball (talk) 13:37, 24 July 2022 (UTC)
  • I oppose this proposal I oppose this proposal. moving pages ending in ":" to ones ending ":*" seems a bit pointless to me as long as it is documented that those ending in colons are prefixes. This mostly seems to just introduce new opportunities for broken links. If we're going to establish a better convention for prefixes and suffixes it really should eliminate the hack of describing them like they're complete keys. --InsertUser (talk) 13:42, 24 July 2022 (UTC)
As explained in the proposal ":*" is preferred over just ":" because the asterisk works better for suffixes (compare Key::foo to Key:*:foo ... I'd consider the double colon to be quite confusing). I don't understand your worry about broken links nor do I see anything hackish about the proposed naming convention. --Push-f (talk) 14:38, 24 July 2022 (UTC)
I understand the proposal, it's slightly clearer than we have now, I just don't agree the improvement is worth the change. Describing something a key when it is actually a fragment of a key seems a bit hacky to me (at least compared with e.g. KeyPrefix). The broken link concern is just because the more redirects you have the more likely it is that one of them will go sideways with a subsequent edit. --InsertUser (talk) 20:31, 27 July 2022 (UTC)
Yes introducing separate namespaces would make the distinction even more obvious, however I don't think that doing so is a good idea because this would make the pages more cumbersome to reach (e.g. they would not show up in the search autocompletion when searching for e.g. Key:addr). I don't consider redirects to be problematic. --Push-f (talk) 06:14, 28 July 2022 (UTC)
  • I approve this proposal I approve this proposal. --Tordanik 16:38, 29 July 2022 (UTC)
  • I approve this proposal I approve this proposal. --Un1matr1x (talk) 11:24, 31 July 2022 (UTC)
  • I approve this proposal I approve this proposal. --Kjon (talk) 14:01, 31 July 2022 (UTC)
  • I approve this proposal I approve this proposal. --R2d (talk) 13:53, 1 August 2022 (UTC)
  • I approve this proposal I approve this proposal. --Dakon (talk) 15:48, 1 August 2022 (UTC)
  • I approve this proposal I approve this proposal. --Dr Centerline (talk) 18:55, 2 August 2022 (UTC)
  • I approve this proposal I approve this proposal. --Famlam (talk) 09:52, 6 August 2022 (UTC)