Policy API early expiration

[kheraankit]

A city operation defines a policy with a start and end date. Example: They define a no operating zone due to planned work going on the streets, for 2 days. The work gets finished earlier and now the city operator would like to revoke the policy so that vehicles are allowed. Currently, the policies are immutable as per the specification.

Describe the solution you'd like

1. Allow the end date to be mutable and let the operators change it but then it goes against the specification and opens the flood gate of updating other fields in the future
2. Create a new policy to override the existing policy [prev_policies] but with empty rules
3. Create a separate endpoint to revoke/delete a policy?

Currently, we are recommending 2 to the city operators but wanted to get suggestions as to how others who have encountered similar use cases are handling it.

Impacted Spec

For which spec is this feature being requested?

• policy

[avatarneil]

We're currently using #2 as well. This makes it clear when the change occurred that nullified the live policy, where as making end_date mutable would not necessarily capture that information (say, for example, if you changed the end_date to 2 days in the future).

#3 would be good too, but I think this starts to fall into the realm of policy authoring, which I believe to date the OMF has not wanted to define an API for because the authorship component is 100% city-side, and not defining a communication mechanism between Providers and Agencies. FWIW, though, we cut a PR a while back for adding a Policy Authoring API #497

#1 I'd be concerned about for precisely the reasons you mentioned!

-- EDIT -- Wrapped the numbers in backticks to avoid linking to PRs/issues automagically 😅

[kheraankit]

@avatarneil Thanks! We recommend #2 as well at Lime.

It would be nice if we can add an example for the same to policy examples.

[kheraankit]

@schnuerle Can we update the document to state policies are immutable and add specific examples showing the early end of policies? We have encountered a few cases from cities and 3rd parties where they have ended the policies early by changing the dates.

[schnuerle]

Ok so for MDS 2.0 we can look at clarifying that policies are immutable, and adding more language to the spec about that. It's mentioned 3 times on the policy page, but maybe a new section about 'Updating or Ending Policies' that could be linked to is in order. Also adding an example with how to properly end or update a policy.

https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy#policies

[xavfernandez]

2. Create a new policy to override the existing policy [prev_policies] but with empty rules would also have my preference.

But currently the JSON schema of policies seem to explicitly forbidden a policy with empty rules:

mobility-data-specification/policy/policy.json

Lines 67 to 76 in 2670581

	"rules": {
	"$id": "#/definitions/rules",
	"type": "array",
	"description": "Array of applicable Rule objects",
	"items": {
	"$id": "#/definitions/policy/properties/rules/items",
	"$ref": "#/definitions/rule"
	},
	"minItems": 1
	}

(which was added in https://github.com/openmobilityfoundation/mobility-data-specification/pull/576/files#diff-c3c8c9c2d57f7519fe41d13c5b30d143c5e5e69fa3beb2f56a7cbdf5390c7a26R75 ) even though https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/policy/README.md does not mention anything about this limitation.
Is the JSON schema wrong and should "minItems": 1 be removed ?

[avatarneil]

@xavfernandez Oof, good catch. I think that the JSONSchema is wrong here, the minItems requirement should be removed IMO.

[schnuerle]

This "minItems": 1 issue should be fixed with the MDS 2.0 OpenAPI work to be done in #281

Will be adding a new section called 'Updating or Ending Policies' with new language, and adding an example to policy examples page.

[schnuerle]

See #680 for the new section and language to clarify "Updating or Ending Policies". Leave feedback here or in the PR.

I don't think an example is needed for this based on the clarified text. Examples also went through a lengthy review to ensure they matched real world common use cases. However, if anyone would like to propose an example, suggest it with specifics here and we could add it now, or in the next release with more review.

[schnuerle]

Continue to leave comments here and if needed we can make tweaks during release review process.