mobility-data-specification Add hierarchy/grouping to policy rules

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_parameters groups the fields describing the rule itself, what is it allowing or disallowing
applies_to groups the fields that limit where/what/when the rule is applicable
rate groups 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.

Jul 23 '21 00:07 jiffyclub

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_ and rate_ 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 👍 !

Jul 23 '21 02:07 jrheard

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.

Jul 24 '21 00:07 jiffyclub

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.

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