Policy API: clarify meaning of `start_date` and `end_date` parameters

[jrheard]

Is your feature request related to a problem? Please describe.

I'm confused by the wording of the documentation of the /policies endpoint's query parameters. It says:

• that the meaning of start_date is "Earliest effective date; default is policies effective as of the request time"
• that the meaning of end_date is "Latest effective date; default is all policies effective in the future"

What's the meaning of "effective date" in this context? Is it the policy's start date, or is it referring to the "effective date range", i.e. the entire period of time during which the policy was active?

Let's say that a particular /policies endpoint is backed by a database containing just one policy, and that the policy has a .start_date of January 1 2021 and an .end_date of January 30 2021.

How would these start_date query parameter values affect the endpoint's response?

• December 1 2020
• January 5 2021
• February 10 2021

How would these end_date query parameter values affect the endpoint's repsonse?

• December 1 2020
• January 5 2021
• February 10 2021

I originally thought that the query parameters would be used to filter for all policies that were active during any point between the specified start_date and end_date, but on a closer read I'm beginning to think that the parameters are actually meant to filter for policies whose start date is within the specified range, because Geography.effective_date explicitly refers to Policy.start_date (policies don't have a documented concept of an "effective date", Geography.effective_date was the closest thing I could find).

But then I go back to the wording of end_date, which is documented as "Latest effective date; default is all policies effective in the future", and it seems unlikely to me that the default behavior of the /policies endpoint is to only return policies whose .start_date is in the future, so I don't know. Now I think that the documentation probably means "effective date range" after all.

Describe the solution you'd like

I think that the README should be reworded so that the behavior of these query parameters is clear.

Is this a breaking change

No

Impacted Spec

For which spec is this feature being requested?

• policy

[janedotx]

Your original interpretation of "effective date range" is correct. Assuming an end_date that defaults to the current time, 12/1/20 and 1/5/21 start_dates will return the policy, but 2/10/21 wouldn't. Assuming a start_date parameter of say, 11/1/20, then an end_date of 12/1/20 wouldn't return the policy, but 1/5/21 and 2/10/21 would.

I'll think about how to clarify the language and maybe stick in some examples of how those query parameters should work.

[schnuerle]

If someone could make a PR for this by the end of the week with clarifying language and an example, it may be included in the forthcoming 1.2.0 MDS release. Otherwise we can revisit it in the next major 2.0.0 release.

[jean-populus]

Is this still a pressing issue we want to address or is it ok to close it for now?

[schnuerle]

Looks to be completed with #742.