Skip to content

Commit 98cbe02

Browse files
FloEdelmannk-yle
FloEdelmann
and
k-yle
authored
prepare changelog and migration guide for v7 (#259)
--------- Co-authored-by: Kyle Hensel <k.y.l.e@outlook.co.nz>
1 parent 01ad96d commit 98cbe02

2 files changed

Lines changed: 223 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,95 @@
77
[#x]: https://github.com/ideditor/schema-builder/issues/x
88
-->
99

10+
# Unreleased
11+
##### (????-???-??)
12+
13+
###### Breaking changes
14+
15+
> [!IMPORTANT]
16+
> see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for more details about each breaking change.
17+
18+
* :warning: Allow multiple values in `prerequisiteTag` property ([#87], thanks [@k-yle])
19+
* :warning: Add _schedule_ field type ([#101], thanks [@1ec5])
20+
* :warning: Add _integer_ field type ([#217], thanks [@k-yle])
21+
* :warning: Store `terms` and `aliases` as an array in the translation files ([#227], thanks [@k-yle])
22+
* :warning: Support discarding tags, not just keys ([#231], thanks [@k-yle])
23+
24+
###### Non-breaking changes, which affect consumers
25+
26+
* Define a schema for relation members ([#174], thanks [@k-yle])
27+
* Auto-generate type definitions from the json schema ([#177], thanks [@k-yle])
28+
* Add `allowDuplicates` property for semi-combo fields ([#178], thanks [@k-yle])
29+
* Dereference at build-time ([#281], thanks [@k-yle])
30+
* Allow icons for radio field ([#291], thanks [@matkoniecz])
31+
32+
###### Non-breaking changes, which do NOT affect consumers
33+
34+
* Allow individual field options to reference other translations ([#230], thanks [@k-yle])
35+
* Fix invalid json schema for the `required` field ([#172], thanks [@k-yle])
36+
* Add `$schema` and `$id` to all json schema for better IDE support ([#173], thanks [@k-yle])
37+
* Fix invalid eslint config ([#176], thanks [@k-yle])
38+
* Fix taginfo file not including base tags for `directionalCombo` ([#222], thanks [@k-yle])
39+
* Fix taginfo file only including the last key-value pair in the object ([#223], thanks [@k-yle])
40+
* Allow fields & presets to reference the `locationSet` from other files ([#226], thanks [@k-yle])
41+
* Consider other unicode commas when splitting translated `terms` ([#228], thanks [@k-yle])
42+
* Make schemas stricter ([#242], thanks [@FloEdelmann])
43+
* Arrays that now have to be non-empty and only allow unique items: deprecated tags, field `keys`/`options`/`terms`, preset `fields`/`moreFields`/`terms`/`aliases`, preset defaults `point`/`vertex`/`line`/`area`/`relation`
44+
* Arrays that now have to be non-empty: field `locationSet.include`/`locationSet.exclude`
45+
* Objects that now have to be non-empty: field `strings`/`strings.options`/`strings.types`/`strings.placeholders`/`locationSet`/`icons`, preset `locationSet`
46+
* Objects that now disallow unknown properties: field `strings`/`strings.options`
47+
* Only strings are now allowed as field `icons` values
48+
* `rtype` is now required in field relation type `reference`s
49+
* `title` and `description` are now required in field `strings.options`
50+
* `name`, `icon` and `members` are now required in preset category
51+
* `point`, `vertex`, `line`, `area` and `relation` are now required in preset defaults
52+
* Add validation for terms to be lowercase and sorted ([#243], thanks [@FloEdelmann])
53+
54+
###### Docs
55+
56+
* Preset properties > `name`: Explain edge case of presets with underscore ([#147], thanks [@tordans])
57+
* Explain that references don't respect the underscore convention ([#148], thanks [@tordans])
58+
* Fix typo ([#171], thanks [@matkoniecz])
59+
* Update directionalCombo docs to mention `:both` ([#179], thanks [@k-yle])
60+
* Document "strings" with "title" and "description" ([#205], thanks [@tordans])
61+
* Icons: Make table and add preview ([#254], thanks [@tordans])
62+
* Better phrasing in documentation of referencing ([#256], thanks [@matkoniecz])
63+
* link opening hours specs ([#274], thanks [@matkoniecz])
64+
* fix some typos ([#292], thanks [@matkoniecz])
65+
66+
[#87]: https://github.com/ideditor/schema-builder/pull/87
67+
[#101]: https://github.com/ideditor/schema-builder/pull/101
68+
[#147]: https://github.com/ideditor/schema-builder/pull/147
69+
[#148]: https://github.com/ideditor/schema-builder/pull/148
70+
[#171]: https://github.com/ideditor/schema-builder/pull/171
71+
[#172]: https://github.com/ideditor/schema-builder/pull/172
72+
[#173]: https://github.com/ideditor/schema-builder/pull/173
73+
[#174]: https://github.com/ideditor/schema-builder/pull/174
74+
[#176]: https://github.com/ideditor/schema-builder/pull/176
75+
[#177]: https://github.com/ideditor/schema-builder/pull/177
76+
[#178]: https://github.com/ideditor/schema-builder/pull/178
77+
[#179]: https://github.com/ideditor/schema-builder/pull/179
78+
[#205]: https://github.com/ideditor/schema-builder/pull/205
79+
[#217]: https://github.com/ideditor/schema-builder/pull/217
80+
[#222]: https://github.com/ideditor/schema-builder/pull/222
81+
[#223]: https://github.com/ideditor/schema-builder/pull/223
82+
[#226]: https://github.com/ideditor/schema-builder/pull/226
83+
[#227]: https://github.com/ideditor/schema-builder/pull/227
84+
[#228]: https://github.com/ideditor/schema-builder/pull/228
85+
[#230]: https://github.com/ideditor/schema-builder/pull/230
86+
[#231]: https://github.com/ideditor/schema-builder/pull/231
87+
[#242]: https://github.com/ideditor/schema-builder/pull/242
88+
[#243]: https://github.com/ideditor/schema-builder/pull/243
89+
[#254]: https://github.com/ideditor/schema-builder/pull/254
90+
[#256]: https://github.com/ideditor/schema-builder/pull/256
91+
[#274]: https://github.com/ideditor/schema-builder/pull/274
92+
[#281]: https://github.com/ideditor/schema-builder/pull/281
93+
[#291]: https://github.com/ideditor/schema-builder/pull/291
94+
[#292]: https://github.com/ideditor/schema-builder/pull/292
95+
[@1ec5]: https://github.com/1ec5
96+
[@FloEdelmann]: https://github.com/FloEdelmann
97+
[@matkoniecz]: https://github.com/matkoniecz
98+
1099
# 6.5.1
11100
##### 2024-Mar-14
12101

‎MIGRATION_GUIDE.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# v7 Migration Guide
2+
3+
v7 of [id-tagging-schema](https://github.com/openstreetmap/id-tagging-schema) and [schema-builder](https://github.com/ideditor/schema-builder) contains 5 breaking changes, where data consumers will need to take action.
4+
5+
This document is a brief migration guide.
6+
The full list of changes is in [CHANGELOG.md](./CHANGELOG.md).
7+
8+
## 1. Allow multiple values in `prerequisiteTag` property ([#87](https://github.com/ideditor/schema-builder/pull/87))
9+
10+
_Fields_ already had a property called `prerequisiteTag`, which previously supported 3 different formats:
11+
12+
```jsonc
13+
{
14+
// existing formats:
15+
"prerequisiteTag": { "key": "electrified" }, // electrified=*
16+
"prerequisiteTag": { "key": "electrified", "value": "no" }, // electrified=no
17+
"prerequisiteTag": { "key": "electrified", "valueNot": "no" }, // electrified≠no
18+
}
19+
```
20+
21+
v7 introduces 2 new possible formats: `values` and `valuesNot`:
22+
23+
<!-- prettier-ignore -->
24+
```jsonc
25+
{
26+
// existing formats:
27+
"prerequisiteTag": { "key": "electrified" }, // electrified=*
28+
"prerequisiteTag": { "key": "electrified", "value": "no" }, // electrified=no
29+
"prerequisiteTag": { "key": "electrified", "valueNot": "no" }, // electrified≠no
30+
31+
// NEW:
32+
"prerequisiteTag": { "key": "electrified", "values": ["contact_line", "rail"] }, // electrified=contact_line OR electrified=rail
33+
"prerequisiteTag": { "key": "electrified", "valuesNot": ["contact_line", "rail"] }, // electrified≠contact_line AND electrified≠rail
34+
}
35+
```
36+
37+
> [!IMPORTANT]
38+
> Action Required: If you already support `prerequisiteTag*`, implement support for the new subproperties: `values` and `valuesNot`.
39+
40+
## 2. Add `schedule` field type ([#101](https://github.com/ideditor/schema-builder/pull/101))
41+
42+
`schedule` is a new valid field type.
43+
This value is designed for fields that support the [`opening_hours` syntax](https://osm.wiki/Key:opening_hours).
44+
45+
> [!IMPORTANT]
46+
> Action Required: If you don't have a UI for [`opening_hours`](https://osm.wiki/Key:opening_hours), treat `type=schedule` the same as `type=text`.
47+
> Otherwise, activate the [`opening_hours`](https://osm.wiki/Key:opening_hours) UI for fields with `type=schedule`
48+
49+
## 3. Add `integer` field type ([#217](https://github.com/ideditor/schema-builder/pull/217))
50+
51+
`integer` is a new valid field type.
52+
This value is designed for numeric inputs which only support integers, not fractional values.
53+
For examples, `lanes=1.5` is invalid.
54+
55+
> [!IMPORTANT]
56+
> Action Required: Ideally, implement a UI for the new `type=integer` field, which could perhaps show a warning if a decimal is entered.
57+
> If it is not possible to implement a new field, `type=integer` could be treated the same as `type=number` as a short-term solution.
58+
59+
## 4. Store `terms` and `aliases` as an array in the translation files ([#227](https://github.com/ideditor/schema-builder/pull/227))
60+
61+
A breaking change was made to the format of files under the `dist/translations/*` folder.
62+
Previously, the `terms` and `aliases` properties were a string, which did not match the JSON schema.
63+
Now, these properties are arrays of strings.
64+
65+
```diff
66+
--- dist/translations/de.json
67+
{
68+
"de": {
69+
"presets": {
70+
"fields": {
71+
"access": {
72+
- "terms": "zugang erlaubt,freier zugang",
73+
+ "terms": ["zugang erlaubt", "freier zugang"],
74+
},
75+
},
76+
"presets": {
77+
"access": {
78+
- "terms": "werbeschild,schild,poster,neon,fahne,flagge,spam,werbebildschirm",
79+
+ "terms": ["werbeschild", "schild", "poster", "neon", "fahne", "flagge", "spam", "werbebildschirm"],
80+
- "aliases": "Werbeträger\nWerbemittel\nReklame\nReklamefläche",
81+
+ "aliases": ["Werbeträger", "Werbemittel", "Reklame", "Reklamefläche"],
82+
},
83+
},
84+
},
85+
},
86+
}
87+
```
88+
89+
## 5. Support discarding tags, not just keys ([#231](https://github.com/ideditor/schema-builder/pull/231))
90+
91+
The format of `discarded[.min].json` has changed.
92+
Previously it was an object, where the value was always `true`.
93+
Now the value can either be `true` or a sub-object.
94+
95+
```jsonc
96+
// discarded[.min].json
97+
{
98+
// OLD: the value must be `true`
99+
"created_by": true,
100+
"odbl": true,
101+
102+
// NEW: the value can still be `true`, or it can be an object which lists the tag values
103+
"odbl:note": true,
104+
"attribution": {
105+
"yes": true,
106+
},
107+
}
108+
```
109+
110+
In the example above, the following tags should be considered discardable:
111+
112+
- `created_by=*`
113+
- `attribution=yes`
114+
115+
Any other values of the `attribution` tag should NOT be discarded.
116+
117+
> [!IMPORTANT]
118+
> Action Required: If you use this file, ensure that your code handles the new format.
119+
120+
## 6. No more references ([#281](https://github.com/ideditor/schema-builder/pull/281))
121+
122+
If you currently parse the fields `stringsCrossReference` or `iconsCrossReference`, or if you handle the reference syntax (such as `"{natural/beach}"`), all this logic can be now be deleted.
123+
124+
References are now expanded at build-time, so fields like `stringsCrossReference` and `iconsCrossReference` will never be exposed to downstream consumers. Likewise for references such as `"{natural/beach}"`.
125+
126+
While this marginally increases the file size, it significantly simplifies the logic for consumers.
127+
It also allows iD-tagging-schema to implement new internal referencing logic (such as [#230](https://github.com/ideditor/schema-builder/pull/230)), without creating a breaking change for consumers.
128+
129+
> [!IMPORTANT]
130+
> Action Required: None. Optionally, you could delete this logic from your code.
131+
132+
## 7. Other changes
133+
134+
See the [CHANGELOG.md](./CHANGELOG.md) file for the 3 other non-breaking changes to the schema.

0 commit comments

Comments
 (0)