Talk:Key:opening hours/specification

Problems

Hours past midnight - the only comment about this is "If time wraps over midnight are involved then you will probably also need". Probably seems rather unclear. Is there a definition for how to write hours past midnight?

As currently documented, multiple fallback rules, matter of fact multiple fallbacks to the fallbacks, are allowed. What about -simplifying- the grammar instead of allowing for endless more variants, with no actual use, no sensible interpretation and no implementation. SimonPoole (talk) 06:15, 11 August 2014 (UTC)

Specifying it this way is just simpler (not limiting the use of fallback rules). This is also supported by the evaluation tool. Note that you can also add additional selectors to fallback rules (which could be handy in some cases). What exactly do you mean by "simplifying"?? You might want to read my opinion about the syntax ;)--Ypid (talk) 23:19, 20 August 2014 (UTC)

Monthday range not defined

<monthday_range> is not defined SimonPoole (talk) 10:05, 19 August 2014 (UTC)

Thanks, fixed it.--Ypid (talk) 00:24, 21 August 2014 (UTC)

Resolved: fixed by Ypid

Whitespaces

The grammar suffers greatly from not specifying where white space is needed and where not, example is 2001Jan-Mar correct or 2001 Jan-Mar SimonPoole (talk) 10:30, 19 August 2014 (UTC)

Thanks very much. I am on it. Adding a space symbol is my next task. The evaluation tool can tell you where spaces are expected in the meantime. --Ypid (talk) 23:19, 20 August 2014 (UTC)

I agree with Simon. The current version has some <space>s defined, but actually, all of these seem to be pretty much optional (e.g. why should "+3days" for the day offset not be allowed?; why should a space behind a rule separator be mandatory?). There should be a difference between what is considered the canonical form and what is valid according to the specification.

As it stands now, pretty much all spaces seem to be optional, except where two successive tokens are either both alphabetical or both numerical (e.g. `week05␣05:00`, `Su␣sunset` but `Jan05Mo-Fr08:00` is fine) --Westnordost (talk) 19:07, 8 January 2024 (UTC)

holiday sequence / weekday sequence

The semantic difference between

<holiday_sequence> , <weekday_sequence>

and

<holiday_sequence> <space> <weekday_sequence>

needs to be documented. BTW I believe the eval tool doesn't actually support SH,PH <weekday_sequence>. SimonPoole (talk) 12:42, 29 June 2017 (UTC)

Thanks, you are right. Spec updated and issue tracked: https://github.com/opening-hours/opening_hours.js/issues/233 (the issue might already be tracked somewhere else, I definitely noticed it already …).--Ypid (talk) 14:53, 29 June 2017 (UTC)

the addition should be linked to <weekday_selector> not <weekday_range> though.

Editing wiki tables has never been more fun (not). Fixed, thanks.--Ypid (talk) 16:15, 29 June 2017 (UTC)

Resolved: fixed by Ypid

month intervals

For

[ <year> ] <month> - <month> / <positive_number>

the unit of <positive_number> is not defined.SimonPoole (talk) 12:46, 29 June 2017 (UTC)

Note: the specific syntax doesn't actually seem to be in use, and could be potentially deprecated/removed.SimonPoole (talk) 13:11, 29 June 2017 (UTC)

Not quite following. "Integer greater than zero". It is basically a count and not a real unit. Do you have a hint what you mean? You can also update the spec directly :)--Ypid (talk) 14:53, 29 June 2017 (UTC)

well does the count refer to days, weeks, months, centuries :-)?

Ah, right. In other occurrences of <positive_number> the unit is inferred from the previous unit. I think you are right that the syntax was never used. It seems this was a copy paste mistake when I was porting the spec from Netzwolf to the wiki syntax in https://wiki.openstreetmap.org/w/index.php?title=Template:Key:opening_hours/specification_table&oldid=1486201. opening_hours.js also does not support it. I removed it. Do you have this implemented by any chance?--Ypid (talk) 16:15, 29 June 2017 (UTC)

The parser parses it, but I didn't actually add an UI because I couldn't really add a reasonable label. SimonPoole (talk) 17:47, 29 June 2017 (UTC)

Resolved: was removed from spec by Ypid

Ramadan as variable_date

In islamic countries restaurants are closed or have different opening hours during ramadan. Because ramadan is not always the same number of days, we might need both the beginning of ramadan and Eid. Elgaard (talk) 17:46, 6 September 2015 (UTC)

Sounds good. I guess defining it as <variable_date> makes sense. Maybe something like ramadan_begin and ramadan_end. Alternative tagging would be defining a second <plural_day_holiday>. I am not yet sure what is best here. Is there a need to refer the first and last day explicitly? Like specifiying different opening hours for the day before the beginning? Can you write an proposal for that? Checkout Proposed_features/opening_hours_open_end_fixed_time_extension as an example. Also you need to define how to calculate the ramadan dates or otherwise provide that information.--Ypid (talk) 19:06, 6 September 2015 (UTC)

Yes, plural_day_holiday is probably better. Because we can have two ramadan_begin in one Gregorian year, happens next time in 2030 Elgaard (talk) 18:00, 7 September 2015 (UTC)

Thanks for the info. In that case use plural_day_holiday … --Ypid (talk) 19:57, 7 September 2015 (UTC)

Daylight saving time as variable_date

Would it be possible to have periods where daylight saving is in effect as a variable date? Something along the lines of dst?

Adavidson (talk) 05:42, 11 January 2017 (UTC)

I came across the same problem today and I think it is common enough to add it to the specification because without it, the values can easily become quite complex as in the following slightly overspecific example (overspecific because the "-1 day" part is not strictly needed if there are no opening hours on sundays):

Oct Su[-1] - Mar Su[-1]-1 day:  Mo 16:00-18:00; Oct Su[-1] - Mar Su[-1]-1 day: Fr 15:00-18:00 ; Mar Su[-1] - Oct Su[-1]-1 day: Mo 17:00-19:00; Mar Su[-1] - Oct Su[-1]-1 day: Fr 16:00-19:00;  PH off

It would also makes sense if the "<wide_range_selectors>" could be applied to multiple "<small_range_selectors>" like it's possible in a <time_selector> (i.e., separating multiple <timespan> by a comma) but that's something somebody who has designed the grammar needs to investigate... it might require some parantheses or so. :)

--Stefanct (talk) 07:57, 17 August 2020 (UTC)

Spec to restrictive. PH,Mo-Fr allowed but Mo-Fr,PH is not.

As noticed in JOSM #18807, the spec currently only allows PH,Mo-Fr but not Mo-Fr,PH. Without checking the database, my impression is that both is used interchangeably. Also because https://openingh.openstreetmap.de/evaluation_tool/ parses both and gives no warning. More research is needed but then I would propose to update the spec. This is not a new feature. It is just that the spec does not match reality so no Proposal process is needed. Thoughts?--Ypid (talk) 17:18, 1 March 2020 (UTC)

I actually looked into this already. Ref: https://github.com/opening-hours/opening_hours.js/issues/293 --Ypid (talk) 17:21, 1 March 2020 (UTC)

I updated the spec.--Ypid (talk) 17:29, 1 March 2020 (UTC)

Resolved: spec was updated by Ypid

Renaming some symbols in the syntax diagram

I think <time_domain> would better be called <rule_sequence>, since it literally is a sequence of rules, and <rule_sequence> should be called <rule>, since it describes a single rule, not a sequence of rules.

Also, I would rename <wide_range_selectors> and <small_range_selectors> to <wide_range_selector> and <small_range_selector>, respectively, since all other symbols also use the singular. AxelBoldt (talk) 22:50, 17 July 2021 (UTC)

And the headline "month selector" in the syntax diagram should be renamed "monthday selector" to stay consistent with the symbol name. AxelBoldt (talk) 21:00, 19 July 2021 (UTC)

In the syntax diagram for <small_range_selectors>, there should be a <space> between <weekday_selector> and <time_selector>. AxelBoldt (talk) 22:44, 19 July 2021 (UTC)

Ambiguity with "," separator

There's another problem with the syntax diagram: the opening_hours "Mo 09:00-12:00, 13:00-18:00" is probably intended as a single rule about Mondays, but it could mistakenly be interpreted as a rule about Mondays, and an additional rule covering all days. AxelBoldt (talk) 23:21, 19 July 2021 (UTC)

Yeah, the same issue exists for any other syntax that involves commas, e.g. "Jan-Jul Mo-Fr, Sa": Is it always open on Saturday, or is it open on Saturday between Jan-Jul. The answer I think is pretty clear, as with your example: The "," separators should be parsed eagerly, i.e. prefer the "," to refer to the list on the same level as the preceding value. So, only if nothing else can be parsed, "," means the beginning of a new rule (with additional modifier).

I think every parser around interprets these strings as the way described, so we could go ahead and document it properly. However, I find it hard to find clear words to describe this behavior. --Westnordost (talk) 19:43, 8 January 2024 (UTC)

Is this case for <monthday_range> missing: <date_from>[ <day_offset> ] ?

I am missing a simple case for <monthday_range> in the grammar: <date_from> [ <date_offset> ]

At the moment there are only these 2 cases with [ <date_offset> ] (and in the first case, that "+" wasn't written as optional "[+]"):

1. <date_from> [ <date_offset> ] +
2. <date_from> [ <date_offset> ] - <date_to> [ <date_offset> ]

Example: I need an opening hour for the First Advent Sunday only, and I hope it could be written like that: Dec 25 -Su -21 days: [ <time_selector> ]

This doesn't seem to be covered by the grammar. Or am I wrong? Goodidea (talk) 01:26, 4 June 2022 (UTC)

You are reading the current spec right, it doesn't seem to be allowed. However, it was in the spec before. It was removed in https://wiki.openstreetmap.org/w/index.php?title=Template:Key:opening_hours/specification_table&diff=prev&oldid=1157093 , though reading the linked forum thread and the problem presented, I am pretty sure that this change was unintended. They wanted to solve the problem that "1-2" is a valid opening hours string, meaning "day 1 to day 2 (of a month)", which doesn't make much sense without the month(s) specified. This was possible because a <date> could be just a <daynum>. So they changed it so that <daynum> could only come after the range "-" sign, i.e. "Jan 1-2" (short for "Jan 1 - Jan 2") is fine.

Simon Poole's opening hours parser https://github.com/simonpoole/OpeningHoursParser also parses it.

So, I think it should be changed to <date_from> [ <date_offset> ] again. Just not sure about the semantic versioning - does this constitute a fix, or should this be counted as a new version? --Westnordost (talk) 22:40, 21 December 2023 (UTC)

Did this now --Westnordost (talk) 22:35, 4 January 2024 (UTC)

Resolved: corrected specification, increased version to 0.7.2

Undocumented extensions to spec 0.7.2

Let's document the extensions to the spec that are supported by the reference implementation (opening_hours.js) and also Simon Poole's Java implementation (used by Vespucci, JOSM, StreetComplete)! The following syntax is also used "in the wild". Changes are highlighted in green:

E.g. Jan Th[2] - Jul Sa[-1] means "from the second Thursday in January to the last Saturday in July". Note (for implementers) that for non-ranges, there is some collision / overlap with weekday selectors: Jan Th[2] is already in the spec, Th[2] being a <weekday_range>. This means that this case could then either be parsed as a date or a monthday range plus weekday range (doesn't change its semantic, though). Jan-Jul Th[2] means "Every second Thursday from January to July"

Symbol	Definition	Comment
<date_from>	[ <year> ] <month> <daynum>
	[ <year> ] <month> <wday> [ [-]<nth> ]
	[ <year> ] <variable_date>

--Westnordost (talk) 14:33, 10 January 2024 (UTC)

Simplify months and dates selector (disallow syntax variations on within-month-ranges that make no sense)

The current version of the spec allows some useless and overcomplex syntax that is, by the way, also not supported by the reference implementation and because it doesn't really make sense or is unreadable, not actually used anyway. E.g.

• Jan 03 +3 days - (three days after January third) - Doesn't make sense. Also, I imagine very difficult to correctly evaluate, when the offset results to be in a different month (Jan 31 +5 days)

• easter-15 -1 day - (from easter till one day before the 15th of whatever month easter is in) - It doesn't make sense to specify the end of a date range within a month only with a day number

• Jan 03 +Su-15 -Sa - (The Sunday after January third till the Saturday before the 15th of the same month) - The syntax is confusing. It can also be written like Jan 03 +Su - Jan 15 -Sa, which is less confusing to read. The only mode in which the shorthand syntax (=omitting the month name for the end of the range) makes sense, is something like Jan 03-15 - without offsets.

I propose to change it to this:

Symbol	Definition	Comment
Months and Dates selector
<months_or_dates_selector>	<months_or_dates> { , <months_or_dates> }
<months_or_dates>	[ <year> ] <month>
	[ <year> ] <month> - <month>
	<date>	Explanation
	<date> +	Explanation
	<date> - <date>	Explanation
	[ <year> ] <month> <daynum_selector> { , <daynum_selector> }
<date>	[ <year> ] <month> <daynum> [ <wday_offset> ]
	[ <year> ] <variable_date> [ <wday_offset> ] [ <day_offset> ]
<variable_date>	easter	Explanation
<wday_offset>	[ <plus_or_minus> <wday> ]	Explanation
<daynum_selector>	<daynum>
	<daynum> - <daynum>

This also documents the capability of the reference implementation (and the Java OpeningHoursParser) to parse Jan 03,06-18,31 (January 3rd, 6th to 18th and 31st).

--Westnordost (talk) 22:53, 18 January 2024 (UTC)

Update spcification to the opening_hours.js-reality for point-in-time syntax

For the point-in-time syntax e.g. "Mo 05:30-06:00/5" the specification is outdated compared with the opening_hours.js code on https://openingh.openstreetmap.de/evaluation_tool/. Fabi2 (talk) 15:02, 7 April 2024 (UTC)

How so? I see

<time> - <extended_time> / <minute>

in the table. --Westnordost (talk) 20:24, 7 April 2024 (UTC)