Add hierarchy/grouping to policy rules #663
Description
Is your feature request related to a problem? Please describe.
A policy rule is a fairly large document with some fields more related to each other than others. I think grouping some fields into sub-sections would improve the interpretability of rules.
Describe the solution you'd like
Here's my proposed grouping of the current rule fields:
{
"name": "",
"rule_id": "",
"rule_type": "",
"rule_parameters": {
"rule_units": "",
"minimum": 0,
"maximum": 1,
"value_url": ""
},
"applies_to": {
"geographies": [],
"states": {},
"vehicle_types": [],
"propulsion_types": [],
"start_time": "",
"end_time": "",
"days": [],
},
"rate": {
"rate_amount": 2,
"rate_recurrence": ""
},
"messages": {}
}This helps group related concepts within the rule and makes the overall rule easier to interpret:
rule_parametersgroups the fields describing the rule itself, what is it allowing or disallowingapplies_togroups the fields that limit where/what/when the rule is applicablerategroups the fields related to a monetary fee, penalty, or subsidy associated with the rule
Is this a breaking change
A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint).
- Yes, breaking
Impacted Spec
For which spec is this feature being requested?
policy
Describe alternatives you've considered
The main alternative is keeping the rule structure flat. That has the advantage of not being a breaking change. A nested structure could be considered more complex than a flat structure, but I would argue that a large number of fields in a flat structure can actually be more complex because it makes it harder to interpret how the fields are used.
Additional context
N/A.
Activity
jrheard commentedon Jul 23, 2021
I think this is a great idea. I've been working with the Policy/Rule data model for a while now, and it's confusing! They're flat objects with tons of fields, and you have to peer at the documentation to figure out the relationship between the various fields, and it takes a long time to build confidence that you've assembled a correct mental model of how things work. I think that adding a layer of nesting+grouping would do wonders to help with that.
Your initial suggested grouping looks pretty reasonable, I'll think about it more and will suggest changes if I think of anything, but no structural improvements jump out at me so far. As a nitpick, I'd suggest dropping the
rule_andrate_prefixes from the newly-nested fields' names as long as we're making changes, but that's super minor. Thanks for thinking about this, I'd definitely love to hear what other people think.In particular, I think it's interesting to consider whether a purely quality-of-life issue (as opposed to a correctness issue or a new-functionality issue) is worth making a breaking change for. I personally think that it's worth it in this case, because IMO the Policy data model as it currently stands is complex enough that I have very little confidence that any two implementations of it will agree with each other. I think your proposal would make a noticeable dent in that problem, so I'm a 👍 !
jiffyclub commentedon Jul 24, 2021
Along the lines of "I have very little confidence that any two implementations of it will agree with each other", I also had that thought and would love to have something like a test suite for policies, in addition to the examples that are already there, where a test suite is a policy, several example events, and the correct results of applying the policy to those events.
janedotx commentedon Jul 26, 2021
You're definitely right, we could use some better documentation for the policies and the expected compliance outcomes. In the meantime, you can check out the 0.4 reference implementation here: https://github.com/openmobilityfoundation/mds-core/tree/dev/packages/mds-compliance
ezmckinn commentedon Nov 10, 2021
I agree with the comments above. This structure seems much clearer to me.
schnuerle commentedon Dec 19, 2022
I don't think this concept will make MDS 2.0. @jean-populus can you confirm?
schnuerle commentedon Jan 2, 2023
We'd need to review this PR before Thursday to ensure it can make the 2.0 release.
schnuerle commentedon May 30, 2024
@jiffyclub What do you think about this now with the changes in MDS 2.0? Do you think hierarchy/grouping in Policy is needed now?
schnuerle commentedon Jul 25, 2025
Closing this because of 2.0 changes. If needed still, reopen or start a new issue.