[Policy] Allow ending a policy by setting its end_date instead of publishing an empty “tombstone” policy

Aperta
  • Qualcosa non va?
#996 0 commenti 1 reazione 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
18/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Ambito
api

Direzione di ricerca

The change is a spec-level design decision, so start in the policy documentation linked as "Updating or Ending Policies" in the policy folder of the repository. Read how immutability and prev_policies are currently defined, then work out which schema and API descriptions would need to allow an end_date-only update. Done means maintainers have agreed the rules (timing, breaking-change status) and the spec text is updated to match, which needs a design discussion before any edit.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Today, ending a published policy requires publishing a new policy with empty rules and listing the ended policy in prev_policies (Updating or Ending Policies). Policies are immutable, so the original policy’s end_date cannot be set or shortened, even when it was published as null. To end a policy we must publish a "tombstone policy" that overloads the API and isn't more readable to operators.

This creates several issues for all parties:

  • Artificial policy objects. The “tombstone” policy carries no rules, but all required fields still have to be filled with placeholder values: name, description, mode_id, start_date and published_date. Every consumer has to special-case “policy with 0 rules = termination”.
  • The ended policy still looks active if polled using its specific UUID. Its own end_date is unchanged, so GET /policies/{policy_id} and start_date/end_date range queries still return it as effective. To know whether a policy is in force, consumers must reverse-scan every policy’s prev_policies.
  • It’s unclear what happens if the tombstone itself has an end_date. Does the original policy come back? TEdious and complicated
  • Uniqueness rule. Multiple tombstones with generic names and empty rules are close to being “functionally identical” policies, which is not what we want to have, and overloads the API making it harder to read.
  • For auditing purposes, it would be easier to have the policy modified with its proper end_date to easily know when it was actually in force, instead of walking prev_policies chains.
Describe the solution you'd like

Allow an agency to end a published policy by updating its end_date, as the only permitted mutation:

  • end_date may be edited after the initial publication of the policy. No other field may change.
  • The new end_date must not be in the past at the time of the update time, so there are no retroactive terminations.
  • Clarify in “Updating or Ending Policies” that immutability applies to all fields except end_date under these conditions. prev_policies remains the mechanism for replacing a policy with new rules.
Is this a breaking change
  • I'm not sure
Impacted Spec

For which spec is this feature being requested?

  • policy
Additional context

From all the implementations that we have had with the Policy API (from planned events to real-time), we have noticed how the tombstone policy quickly becomes an issue for legibility of the policy endpoint and makes it hard when having auditability conversations with the operators, and internally.

Lingua principale
Nessun dato sulla lingua
Stelle
753
Fork
255
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openmobilityfoundation/mobility-data-specification

Tutte le issue di openmobilityfoundation/mobility-data-specification

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.