Add min/max values for attributes (static counters)

[Kostadin-Ivanov]

Currently some attributes like:

1. Vehicle.Cabin.DoorCount
2. Vehicle.Cabin.SeatRowCount
3. Vehicle.Cabin.SeatPosCount
4. Vehicle.Chassis.AxleCount
5. Vehicle.Chassis.Axle.WheelCount

are missing min/max value (constraints), which can lead to some not realistic numbers for OpenAPI or JSON Payload, which can be retrieved using tools like ESMF Aspect Model Editor

Although the above attributes are provided with some default values, it still would be good practice to have min and max entries in such that a generated API / JSON Payload, or even a developer would be aware of the boundaries of these attributes.

For example: without specified default values, the above mentioned ESMF Aspect Model Editor generated OpenAPI and JSON Payload, with some quite unusual counters like: doorCount: 214, axleCount: 118 etc., which were randomly generated with respect to any number without any boundaries.

SUGGESTION: As solution, we suggest that min & max values could be added to the above attributes so there is clear enough limits for these.

For example: if lets say we set an axleCount with min: 2 and max: 4 the VSS could easy be used for a regular vehicle with 2 axles up to a truck with 4 axles.

Other example would be related to seatRowCount and seatPosCount. Using min and max values for these can easy cover vehicles from a regular car with 5 seats up to a bus with 50 seats.

[erikbosch]

Some historic background:

In the past the VSS standard catalog quite often had arbitrary min/max limits. Like specifying that speed had max: 300. They were removed as available min/max values typically are context/vehicle dependent. Like if you are to design an analog or digital speedometer in a User Interface, it makes sense to know the range that you need to be able to display, but a budget car will not have the same range as a sports car or a tractor. So the default min/max were removed in most cases, and instead VSS users needs to add it as an overlay or by any other mechanism.

I am not sure if I follow the argumentation. In a real use-case the counters shall reflect the instances they represent, so it shall only report 118 axles if there are 118 axles in the vehicle. However, if a system/context does not need to handle vehicles with more than 3 axles, then it could be relevant to have a min/max for that particular system/context.

[Kostadin-Ivanov]

Hello Erik, and thank you very much for this clarification.

I got the impression that VSS is more general and would provide definitions of various vehicle attributes, properties or signals on a broader range so more models / makes and types of vehicles can be easy covered by this specification. In other words it would be more general and will not be focused on some particular vehicle type, model etc. Also, I was not aware that VSS users would be able to edit / adjust it based on their needs.

Maybe is because we used the general VSS to build our models straight of the VSS, which we further plan to reuse in more customized such models, using the ESMF Aspect Model Editor, and then we noticed these missing boundaries for some of these counters.
I understand that one can easy and logically put some realistic numbers to these counters, but it would still be good to know the boundaries of such attributes. Especially when it comes that the VSS is to be interpreted / parsed by some machine code / script. Not that the owners of this script cannot add some additional logic / rules for such limits, but it would be very handy if these were provided by the VSS specification itself.

I think that this way it would be more abstract and cover wide range of vehicles / machines, and then users would easy adjust according to it, instead of having to further customize the VSS based on their needs / use cases.

Anyway, could you please tell me where can I read a bit ore for these "overlays" and mechanisms to "modify" the VSS to familiarize myself with these practices?

Thank you in advance.

[erikbosch]

Some info on overlays can be found at https://covesa.github.io/vehicle_signal_specification/rule_set/overlay/. You could also look on some of the test cases that exist, like https://github.com/COVESA/vss-tools/tree/master/tests/vspec/test_overlay

[Kostadin-Ivanov]

Thank you very much.
Having this functionality, can we add an overlay with min/max values for the above mentioned counters in dedicated overlay so it can be shared within VSS with other users?

If yes, can we implement this and create corresponding PR for this update?

Then we can update our scripts to work with these overlays.

[SebastianSchildt]

To add to Eriks answer, if you use vss-tools or some in-house tooling based on that, the mechanics iof adding overlays are here https://github.com/COVESA/vss-tools/blob/master/docs/vspec2x.md#handling-of-overlays-and-extensions

Generally with overlays you can

• add VSS elements in the tree
• modify VSS elements in the tree
• augment VSS elements with custom metadata

A more comprehensive public sample of the later can also be found in the CAN config of KUKSA DBC provider: https://github.com/eclipse/kuksa.val.feeders/blob/main/dbc2val/mapping/vss_4.0/dbc_overlay.vspec

Usually in the model here we try to keep the "generic" parts, while things like min/max limits or default values are considered "deployment information", i.e. something that needs to be tailored to a specific (type of) vehicle. There have been some discussions that actually "instances" are also deployment information and should not have specific values in the standard catalogue, but for now - for historic reasons - they are.

For your problem, I may have not understood it fully. Why do you end up with things like "doorCount: 214, axleCount: 118" - which are of course perfectly valid, just seems an unusual vehicle. Is this a bug/feature in the Mode Editor you use? Are this - as I suspect - random numbers, which are "not aesthetically pleasing"? In that case this seems a very tool-specific hack. If you aim is to have a "generic" model in your tooling, with some "reasonably sane" limits, I think that could be an "ESMF" overlay with some min/max values, but I guess that is not super user useful for other users (prove me wrong :) ), so maybe fits rather as a VSS specific overlay in ESMF repos, just like KUKSA CAN has overlays for the various VSS releases? If your aim is modelling a specific vehicle, I think the overlay should rather override "default" values, e.g. setting doorCount to 4. Then it would be just an "example" of a fully defined vehicle.

[Kostadin-Ivanov]

Hello @SebastianSchildt and thank you for the additional update on this.

Your guess about these high numbers was correct.

Briefly, our goals is to build ESMF models, which are based on the VSS and can be further reused to create more customized models, which then can be used for generation of various APIs, depending on the use case.

We already have this vspec2esmf script on rbs-vss-tools which converts the whole VSS into ESMF Aspect Model Editor (AME) format - models, which we can further reuse to build our custom API models.

Initially ,the script was not handling the default values for some attributes as defined in VSS and for this reason, when we were generating some JSON Payloads, to visualize a possible response for the created API model, or creating OpenAPI configurations, using the AME, we were getting these randomly generated pretty high numbers for some counters.

Our intention was not to customize the VSS before we build our models from it, but rather to use it as general source (standard) to build our custom API models. In other words we expected that the VSS would provide definition for different attributes and in the case of door / seat / axle counters to also specify the available range of these, i.e. the min and max possible numbers of doors, seats, axles etc.

I don't think that I can attach any screenshots of our AME models here, but if you'd like- and have time, feel free to ping me on MSTeams and I can explain our case in more details and can demo to you our VSS based API models on the ESMF Aspect Model Editor.

[Kostadin-Ivanov]

In addition to my comment above:

As I mentioned, our vspec2esmf.py script is provided uner the rbs-vss-tools and is utilizing the rbs-vss-tools/vspec converter, so I am not 100% if we can properly utilize the usage of overlays and extensions.

I will have to double check the rbs-vss-tools to confirm this.

[Kostadin-Ivanov]

Hello @erikbosch and @SebastianSchildt ,

I reviewed our use cases around building Aspect Models, based on the general VSS, and their further reuse to create custom APIs.
Briefly our idea was that being a standard, although not yet defined as such, but obviously going in this direction, we read the VSS read as it is, i.e. we are not going and we should not do any kind of customization of the VSS, before we build our aspect models of it.
The goal is to have general aspect models of VSS signals, which then we can further reuse in customized API - aspect models, without making any adjustments to the VSS itself. For us it is a standard and we should adhere to it, instead of to customize it for our own use cases.
For this reason we think that it would be very handy if there is provided some acceptable (meaningful) range of values for some counters, measurements or other types of signals, i.e. the min and max constraints.
Off course, for some extreme cases, someone can use the overlays so they build their own, customized version of the VSS for their needs, but our idea was more to work with the general VSS standard and as such not to customize it for one or other reason.
Another reason to keep off such customization is to be able to easy keep in sync with latest VSS updates and not to divert too much from its main concept.