Support for "Except" Policies

[zanebclark]

I saw a street sign with a policy followed by "except Holidays and Sundays". We could do the "except Sundays" part by defining a Time Span that specifies all of the days_of_week values except for Sunday. The "except Holidays" part is much harder without the ability to define "subtractive" or "negative" Time Spans.

Policy time_spans starts out entirely negative (the policy doesn't apply) and Time Spans are positive (the policy does apply). If you could define a "negative" Time Span, you could reflect "except" policies by layering "negative" Time Spans on top of "positive" Time Spans. For example:

{
  "time_spans": [
    {
      "days_of_week": [
        "mon",
        "tue",
        "wed",
        "thu",
        "fri",
        "sat"
      ]
    },
    {
      // MLK Jr. Day
      "positive": false, // or "additive": false,
      "days_of_week": [
        "mon"
      ],
      "days_of_month": [
        15,
        16,
        17,
        18,
        19,
        20,
        21
      ],
      "months": [
        1
      ]
    }
  ]
}

In this example, I included two potential ways to express a time span that removes coverage: "additive": false and "positive": false. The default for these attributes would be "true".

[zanebclark]

Based on feedback from the 2/15 meeting, there is some overlap here with the concept ofdesignated_period (
see Time Span).
When designated_period_except is true, the Time Span doesn't apply during the designated_period. This addresses
some needs of "Except" policies, but it has a few limitations:

1. designated_period is a string, not an array. If you wanted to "except" both school days and game days, you
   would have to define and apply a new designated period: school days and game days.
2. How do you fetch the definition of a designated_period? Do we expose a new endpoint for that?
3. What's the schema for designated_period definition? It seems to me that it would need to be a robust model, similar
   to that of Time Span.

A proposal:

Include optional name and category fields on the Time Span object that would a) provide a nice, user-friendly
reference and b) allow for its reuse across multiple policies.

When adding a named Time Span to a policy, any attributes - except for the name - would override those of the
initially defined Time Span. For example, the initial named Time Span definitions:

{
  "name": "MLK Jr. Day",
  "category": "Holiday",
  "days_of_week": [
    "mon"
  ],
  "days_of_month": [
    15,
    16,
    17,
    18,
    19,
    20,
    21
  ],
  "months": [
    1
  ]
}

{
  "name": "Washington’s Birthday / President's Day",
  "category": "Holiday",
  "days_of_week": [
    "mon"
  ],
  "days_of_month": [
    15,
    16,
    17,
    18,
    19,
    20,
    21
  ],
  "months": [
    2
  ]
}

And the use of said Time Span on a policy:

{
  "time_spans": [
    {
      "days_of_week": [
        "mon",
        "tue"
      ],
      "time_of_day_start": "10:00",
      "time_of_day_end": "13:00"
    },
    {
      "name": "MLK Jr. Day",
      "additive": false
    },
    {
      "name": "Washington’s Birthday / President's Day",
      "additive": false
    }
  ]
}

Or, we could "Except" an entire category:

{
  "time_spans": [
    {
      "days_of_week": [
        "mon",
        "tue"
      ],
      "time_of_day_start": "10:00",
      "time_of_day_end": "13:00"
    },
    {
      "category": "Holiday",
      "additive": false
    }
  ]
}

This proposal addresses the limitations of designated period outlined above:

1. time_spans is already an array, so there's no limit to the number of exceptions that could be defined.
   Named Time Span objects allow for reuse across multiple policies.
2. Named Time Span objects could be exposed both on the curbs endpoints, right alongside unnamed Time Span
   objects. For example, when querying the above policy, you would see this:

{
  "time_spans": [
    {
      "days_of_week": [
        "mon",
        "tue"
      ],
      "time_of_day_start": "10:00",
      "time_of_day_end": "13:00"
    },
    {
      "name": "MLK Jr. Day",
      "category": "Holiday",
      "additive": false,
      "days_of_week": [
        "mon"
      ],
      "days_of_month": [
        15,
        16,
        17,
        18,
        19,
        20,
        21
      ],
      "months": [
        1
      ]
    },
    {
      "name": "Washington’s Birthday / President's Day",
      "category": "Holiday",
      "additive": false,
      "days_of_week": [
        "mon"
      ],
      "days_of_month": [
        15,
        16,
        17,
        18,
        19,
        20,
        21
      ],
      "months": [
        2
      ]
    }
  ]
}

Named Time Span objects could also be exposed at another endpoint if there was value in doing that, though the
integrated definition of the Time Span with the Policy definition might undermine the value of a separate endpoint.

3. We're re-using the same schema

[schnuerle]

Points from WG meeting:

1. Need one place to list and reference holidays and not repeat a list of holidays in each policy
2. Need to record what is expected in the future (eg school day list), and what happened in the past (eg snow emergency days) for Metrics reference
3. These lists may grow over the years and based on details provided, so want to think about file size and repetition
4. Should it be in its own endpoint like a /information about agency wide details, or part of /policies in the top metadata, or in /policies somewhere else?
5. Should we record exact dates of future or past events, eg '2022-01-18', or is it ok to say 'MLK Day' or 'Thanksgiving'? Maybe dates are needed for clarity since not every knows US holidays or local holidays, eg 'Mardi Gras', 'Kentucky Derby'.
6. A note about the uniqueness requirement of timespan and user class arrays, and if the spec is clear enough. should it be the combination of timespan and whole set of user classes, and if does that need to be clarified in the spec to avoid potential overlap/conflicts?

[zanebclark]

On 5, I think a timestamp range - from a start timestamp to an end timestamp - would support events that aren't full days.

[zanebclark]

On 6, see #84

[zanebclark]

On 4, I proposed that we could expose an endpoint for all named / categorized time spans in the above proposal:

Named Time Span objects could also be exposed at another endpoint if there was value in doing that, though the
integrated definition of the Time Span with the Policy definition might undermine the value of a separate endpoint.

[jlarsonOmahaNE]

I think there should be a federal/national holiday table somewhat like the data-source-operator table. When it comes down to specific dates like school days or game days, I think these should be in an endpoint so that it is on the data producer to update accordingly. This endpoint could host the main holiday table though.

[zanebclark]

@jacobmalleau, thanks for bringing up school days! That's a good get.

[jacobmalleau]

Another outlier is "sunset to sunrise" which is extra tough. In theory you have to define the times for every single day of the year. Which you can do, but once again you dont want to see that every time you call.