DE:Key:opening hours/specification
Syntax für opening_hours Werte
Diese Spezifikation ist eine Weiterentwicklung der Spezifikation auf netzwolf.info (Kopie).
Sie beschreibt die vollständige Syntax die für opening_hours=* zur Verfügung steht und soll als Referenz für Mapper und Entwickler dienen. Die umfangreichste Implementierung dieser Spezifikation ist opening_hours.js, mit der unter anderem getestet werden kann, ob der eigene opening_hours Wert mit dieser Spezifikation übereinstimmt.
Diese Referenz ist auch in das Auswertewerkzeug integriert um schnell etwas nach zuschauen. Unter dem Punkt „Schön formatierter opening_hours Wert für die Anzeige“ sind die Bestandteile des opening_hours Wert mit der entsprechenden Dokumentation auf dieser Seite verlinkt.
Die Syntax wurde ursprünglich eingeführt um Öffnungszeiten für Einrichtungen zu beschreiben, aber da die Syntax sehr flexibel und umfangreich geworden ist, wird sie ebenfalls für eine Vielzahl anderer Tags in OSM benutzt (Auflistung siehe hier).
Überblick über den Aufbau der Syntax
Jeder opening_hours Wert besteht aus einer oder mehreren Regeln. Eine Regel wird durch einen Regeltrenner von der folgenden Regel separiert. Eine Regel besteht aus einem oder mehreren Bereichsdefinitionen (siehe <selector_sequence>) und keiner, einer oder mehreren Regeleigenschaften (siehe <rule_modifier>). Eine Bereichsdefinition wird benutzt, um einen gewissen Zeitbereich auszuwählen (beispielsweise „Mo-Fr“) wobei eine Regeleigenschaft benutzt werden kann, um die Bedeutung der Regel zu ändern (beispielsweise „closed“).
Legende
- „|“ trennt Alternativen.
- „[“ und „]“ optionale Komponenten.
- „{“ und „}“ optionale wiederholbare Komponenten.
- Mehrere Varianten für ein Symbol stellen Alternativen dar.
- Zeichen oder Wörter, die fett sind, heben Schlüsselwörter (oder Tokens) in der Syntax hervor.
- Beispielwerte sind hervorgehoben.
- Symbole innerhalb der Spezifikation werden so referenziert:
<selector_sequence>
Syntaxdiagramm
Specification version 0.7.2. The specification versioning complies with Semantic Versioning. Increase the version accordingly when updating the specification.
Note that the English version of the specification is considered the official documentation. Translations of the specification might not be up-to-date or in compliance with the latest version yet.
| time_domain | ||
|---|---|---|
| Symbol | Definition | Comment |
| <time_domain> | <rule_sequence> { <any_rule_separator> <rule_sequence> }
|
Explanation |
| <rule_sequence> | Limitations and Explanation | |
| Rule separators | ||
| <any_rule_separator> | <normal_rule_separator> | <additional_rule_separator> | <fallback_rule_separator>
|
|
| <normal_rule_separator> | ; <space>
|
|
| <additional_rule_separator> | , <space>
|
Limitations and Explanation |
| <fallback_rule_separator> | Explanation | |
| Rule modifiers | ||
| <rule_modifier> | → open (Explanation) | |
open [ <space> <comment> ]
|
→ open | |
closed | off [ <space> <comment> ]
|
→ closed (Explanation) | |
unknown [ <space> <comment> ]
|
→ unknown | |
<comment>
| ||
| Selectors | ||
| <selector_sequence> | 24/7 | Explanation |
<wide_range_selectors> <small_range_selectors>
| ||
| <wide_range_selectors> |
[ |
|
<comment>:
|
Explanation | |
| <small_range_selectors> |
[ |
|
| <separator_for_readability> | : | Explanation |
| Time selector | ||
| <time_selector> | <timespan> { , <timespan> }
|
|
| <timespan> | ||
<time>
|
Limitations and Explanation | |
<time> +
|
Explanation | |
<time> - <extended_time> +
| ||
<time> - <extended_time>
| ||
<time> - <extended_time> / <minute>
|
Limitations and Explanation | |
<time> - <extended_time> / <hour_minutes>
| ||
| <time> | <hour_minutes> | <variable_time>
| |
| <extended_time> | ||
| <variable_time> | <event>
|
|
( <event> <plus_or_minus> <hour_minutes> )
|
||
| <event> |
dawn | sunrise | sunset | dusk |
|
| Weekday selector | ||
| <weekday_selector> | <weekday_sequence>
|
Explanation |
<holiday_sequence>
| ||
<holiday_sequence> , <weekday_sequence>
| ||
<weekday_sequence> , <holiday_sequence>
| ||
<holiday_sequence> <space> <weekday_sequence>
| ||
| <weekday_sequence> | <weekday_range> { , <weekday_range> }
| |
| <weekday_range> | <wday>
|
|
<wday> - <wday>
|
||
<wday> [ <nth_entry> { , <nth_entry> } ]
|
Explanation | |
<wday> [ <nth_entry> { , <nth_entry> } ] <day_offset>
|
||
| <holiday_sequence> | <holiday> { , <holiday> }
| |
| <holiday> | <public_holiday> [ <day_offset> ]
|
Limitations and Explanation |
<school_holiday>
|
||
| <public_holiday> | PH | |
| <school_holiday> | SH | Explanation |
| <nth_entry> | <nth>
|
|
<nth> - <nth>
|
||
- <nth>
|
||
| <nth> | 1 | 2 | 3 | 4 | 5 | |
| <day_offset> | <space> <plus_or_minus> <positive_number> <space> day[s]
|
|
| Week selector | ||
| <week_selector> | week <week> { , <week> }
|
|
| <week> | <weeknum>
|
|
<weeknum> - <weeknum>
|
||
<weeknum> - <weeknum> / <positive_number>
|
Explanation | |
| Month selector | ||
| <monthday_selector> | <monthday_range> { , <monthday_range> }
|
|
| <monthday_range> | [ <year> ] <month>
|
|
[ <year> ] <month> - <month>
|
||
<date_from> [ <date_offset> ]
|
Explanation | |
<date_from> [ <date_offset> ] +
|
Explanation | |
<date_from> [ <date_offset> ] - <date_to> [ <date_offset> ]
|
Explanation | |
| <date_offset> | [ <plus_or_minus> <wday> ] [ <day_offset> ]
|
Explanation |
| <date_from> | [ <year> ] <month> <daynum>
|
|
[ <year> ] <variable_date>
|
||
| <date_to> | <date_from>
|
|
<daynum>
|
Explanation | |
| <variable_date> | easter | Explanation |
| Year selector | ||
| <year_selector> | <year_range> { , <year_range> }
|
|
| <year_range> | <year>
|
|
<year> - <year>
|
||
<year> - <year> / <positive_number>
|
||
<year> +
|
||
| Basic elements | ||
| <plus_or_minus> |
+ | - | |
| <hour> |
00 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 |
|
| <extended_hour> |
|
|
| <minute> |
00 | 01 | 02 | 03 | 04 | 05 |
06 | 07 | 08 | 09 | 10 | 11 |
12 | 13 | 14 | 15 | 16 | 17 |
18 | 19 | 20 | 21 | 22 | 23 |
24 | 25 | 26 | 27 | 28 | 29 | |
|
| <hour_minutes> | <hour>:<minute>
|
|
| <extended_hour_minutes> | <extended_hour>:<minute>
|
Explanation |
| <wday> |
Su | Mo | Tu | We | Th | Fr | Sa |
|
| <daynum> |
01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 |
|
| <weeknum> |
01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 |
14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | |
Explanation |
| <month> |
Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec |
|
| <year> | Four digit number greater than 1900. | |
| <positive_number> | Integer greater than zero (not zero padded). | |
| <comment> | " <comment_character> { <comment_character> } "
|
Explanation |
| <comment_character> | Any character except ". | |
| <space> | " " | |
Erklärungen
| time_domain | ||
|---|---|---|
| Symbol | Explanations | |
| <time_domain> ↑ | Eine <selector_sequence> trifft auf einen Tag entweder ganz oder gar nicht zu.
Das Ergebnis einer Auswertung ist das der letzten Regel, welche für diesen Tag zugetroffen hat.
Das bedeutet, dass die letzte Regel, die auf einen Tag zutrifft, alle anderen, die ebenfalls zutreffen, überschreibt.
Falls dies nicht gewünscht ist, kann | |
| <rule_sequence> ↑ | Es ist zu beachten, dass <rule_sequence> nicht leer sein kann. <space> wird nur benötigt, wenn <selector_sequence> und <rule_modifier> nicht leer sind.
| |
| <additional_rule_separator> ↑ | Eine additive Regel verhält sich genau wie eine normale Regel, mit der einzigen Ausnahme, dass eine additive Regel nicht die Tage überschreibt, für die diese zutrifft (im Unterschied zu <normal_rule_separator> welche immer mit einem Tag ohne Zeiten beginnt und alle Zeiten von vorhergehenden Regeln für den gegebenen Tag löscht). Zu beachten ist, dass eine additive Regel keinerlei Informationen von vorhergehenden oder nachfolgenden Regeln benutzt. Falls Zeiten erst nach Mitternacht enden müssen in den meisten Fällen ebenfalls additive Regeln verwendet werden um nicht den Teil, der in den nächsten Tag hineinragt zu überschreiben. Additive Regeln können auch verwendet werden um verschiedene Kommentare für einen Tag zu definieren. Weitergehendes (inklusive Beispielen) kann in einem Ticket auf GitHub nachgelesen werden.
Aufgrund der Tatsache, dass
| |
| <fallback_rule_separator> ↑ | Regeln werden von links nach rechts ausgewertet, bis eine Regel den Status „open“ (offen) ergibt.
Netzwolf hat || als Oder-Verknüpfung zur Syntax hinzugefügt, da es von Mappern nicht zufällig eingetippt werden dürfte und da es von jedem Programmierer sofort verstanden wird. Für die, die es nicht sofort verstehen: Es ist als Oder-Verknüpfung zu verstehen. Die Regel, die nach diesem Begrenzungszeichen (Token) folgt, treffen für jeden Zeitraum zu, der nicht von einer der vorherigen Regeln abgedeckt wurde. | |
| <rule_modifier> (empty) ↑ | Falls kein <rule_modifier> in einer Regel benutzt wurde, dann wird die <rule_sequence> als offen interpretiert.
| |
| <rule_modifier> (closed) ↑ | Regeln mit closed oder off als Regeleigenschaft löschen Tage von vorhergehenden Regeln, auf die diese off Regel zutrifft. Bitte beachte, dass off Regeln nichts anderes überschreiben im Gegensatz zu anderen <rule_modifier>. Siehe dazu auch dieses Ticket auf GitHub.
| |
| <selector_sequence> (empty) ↑ | Gemeint als „immer“. Diese Bereichsdefinition trifft zu jeder beliebigen Zeit zu. | |
| <wide_range_selectors> (no syntax) ↑ | In manchen Fällen können die Tage für eine Regel nicht genau so wie angegeben geschrieben werden.
In diesem Fall kann die Angabe der Tage als normaler Text als Kommentar angegeben werden gefolgt von einem :. | |
| <separator_for_readability> ↑ | Dieses Zeichen ist optional und ändert an der Bedeutung einer Regel nichts. Es wurde in die Syntax aufgenommen, um die Lesbarkeit für Menschen zu erhöhen. Nicht zeitgemäße Implementierungen der Syntax verlassen sich eventuell noch auf das vorhanden sein dieses Zeichens. | |
| <timespan> (point in time) ↑ | Nur gültig im Zeitpunkt-Auswertemodus wie er für Tags wie collection_times=* angewendet wird. | |
| <timespan> (open end) ↑ | „Open end“, „Offenes Ende“: Die Öffnungszeit beginnt zu der angegebenen Zeit und endet zu einer ungewissen Zeit. Diese Formulierung wird oft benutzt, ist allerdings nicht deterministisch. Die Auswertung ist hier beschrieben.
| |
| <timespan> (shortcut for pattern points in time) ↑ | Diese Notation beschreibt ein wiederholtes Ereignis:
„10:00-16:00/90“ und „10:00-16:00/1:30“. Es wird als „von 10 Uhr bis 16 Uhr alle 1½ Stunden“ ausgewertet. Weitere Informationen sind hier zu finden. Nur gültig im Zeitpunkt-Auswertemodus wie er für Tags wie collection_times=* angewendet wird. | |
| <weekday_selector> ↑ | Per <space> getrennte Symbole (<holiday_sequence> oder <weekday_sequence> in diesem Fall) sind und verknüpft was bedeutet das beide Teile zutreffen müssen damit die Regel Anwendung findet.
Per Komma getrennte Symbole sind wie üblich oder verknüpft was bedeutet das mindestens einer der Teile zutreffen muss. | |
| <weekday_range> (n-te weekday in month) ↑ | „Su“ repräsentiert alle Sonntage, „Su[1]“ repräsentiert den ersten Sonntag im Monat, „Su[-1]“ repräsentiert den letzten Sonntag im Monat. | |
| <holiday> ↑ | Zurzeit ist nur eine Tagesverschiebung von einem Tag spezifiziert. | |
| <school_holiday> ↑ | Kann benutzt werden, um Ferien zu definieren. Siehe dazu auch im README auf GitHub (Englisch) oder auf Key:opening_hours. | |
| <week> ↑ | Die Notation wurde von cron „geliehen“ und ermöglicht das Ausdrücken von „an geraden Wochen“ oder „an ungeraden Wochen“. | |
| <monthday_range> ↑ | Resultiert in wahr wenn der zu überprüfende Tag dem angegebenem entspricht. Zu falsch andernfalls.
| |
| <monthday_range> (plus) ↑ | Der Kalenderbereich beginnt am angegebenen Datum und hat keine Begrenzung in der Zukunft. | |
| <monthday_range> (range) ↑ | Resultiert in wahr, wenn start-Datum ≤ zu-prüfender-Tag ≤ end-Datum zutrifft.
Resultiert in | |
| <date_offset> ↑ | Bei einem Kalendertag führt das Anhängen von „+Su“ zur Auswahl zum ersten Sonntag nach diesem Kalendertag,
die Notation „-Su“ wählt dagegen den letzten Sonntag vor diesem Kalendertag aus. | |
| <date_to> (daynum) ↑ | Wenn bei einem <date_to> kein Monat (<month>) angegeben wurde, wird der letzte Monat angenommen. Als Beispiel: „Jan 23-25“ wird als „Jan 23-Jan 25“ ausgewertet.
| |
| <variable_date> ↑ | Es gibt vermutlich noch andere Beispiele für <variable_date> welche Sinn manchen würden. Diese allerdings noch nicht definiert. Falls etwas fehlt, bitte melden.
| |
| <extended_hour_minutes> ↑ | Kann benutzt werden um Zeiten zu beschrieben die über Mitternacht in den nächsten Tag hineinragen. Zeiten, die in den nächsten Tag hineinragen, können ebenfalls ausgedrückt werden, indem die zweite Zeitangabe (beispielsweise 04:00) kleiner ist als die erste Zeitangabe (beispielsweise 22:00). Beispielsweise „Fr,Sa 22:00-04:00“ was einfacher zu lesen sein dürfte. Besonders wenn die zweite Zeitangabe größer als üblich ist (Vergleiche „Fr,Sa 22:00-20:00“ mit „Fr,Sa 22:00-44:00“). | |
| <weeknum> ↑ | Nach ISO 8601 ist „week 01“ die Woche, die den ersten Donnerstag des Jahres enthält. Siehe Wikipedia. | |
| <comment> ↑ | Kommentare können benutzt werden um dem Benutzer zusätzliche Informationen zu geben oder auf Einschränkungen hinzuweisen. Ein Kommentar kann auch benutzt werden, wenn die Öffnungszeiten nicht zuverlässig durch Software bestimmt werden können, da diese auf subjektiven Informationen basieren (Beispielsweise dem Wetter). Die Sprache sollte der Sprache der Region, für die die Öffnungszeiten zutreffen, entsprechen.
Beispiele:
| |