Cross Referencing Specifications - namespace or other

[tguild]

COVESA and the ACEA Fleet Management Standard (FMS) are formally collaborating, mapping their SAE J1939 subset of signals being exposed to fleet owners to VSS to support an onboard API.

We would like to declare the relationships on a per signal level between these specifications as well as be able to support more in general. This might be more of a topic for the emerging Vehicle Data Model activity or we can create a convention to support in VSS either as an overlay or within the official VSS YAML.

Cross referencing other specifications is widely done, as an example VSS is a normative reference in W3C VISS (version 1 and subsequent). For that I needed to add VSS to specref.org where you can find authorative links to a sizeable number of specifications/standards.

For data model definitions, a declared and maintained namespace is preferred, ideally with anchors in the html document for individual data elements. Better still is an alternative, machine readable format residing at the same link and served based on client preferences on content type.

Unfortunately ACEA FMS (latest, version 5) does not have such anchors for the individual signal definitions even though PDF supports internal links, essentially the same as html anchor links. I raised this with them and offered to help add them to their document.

Some specifications lack referenceable online resources, for example all SAE specs are copyrighted and can be downloaded after paying for them. We will need to support both referenceable (linkable) resources as well as non. For J1939, people tend to cite PGN and SPN identifiers.

If a signal in VSS is also defined in/mapable to one or more other specifications, we would like to have those cross references.

ACEA FMS has for example: 1.1.7 High Resolution Vehicle Distance: VDHR maps to VSS Vehicle.TravelledDistance

As an aside the proposed improved TraveledDistance granularity #822 helps with this mapping because distance is FMS is measured in meters instead of kilometers.

We would like to see something like:

TraveledDistance:
datatype: float
type: sensor
unit: km
description: Odometer reading, total distance traveled during the lifetime of the vehicle.
references: ACEA-FMS-VDHR, SAE-J1939-PGN:0xFEC1;SPN:917

(or ACEA-FMS-1.1.7 or after adding anchors https://www.fms-standard.com/Truck/down_load/fms%20document_v_05_vers.24.11.2023.pdf#1.1.7 )

where multiple comma or otherwise separated.

This can and should be done in Vehicle Data Model but it is also desireable in VSS - official or in an overlay.

We would like to get some guidance from COVESA VSS or DEG on how to handle.

[SebastianSchildt]

I really like the idea, but adressing the elephant in the room: While we do try to align to standards out there (and sometimes refer them in comments), the question is, is it ok to reference standards in a machine readable "unambiguous" way.

Extreme example, as we had the discussion in the past: SAE-J1939 is currently not "free for all", i.e. Jon Doe can not just download it (this was also a pain over at Eclipse in some of the SDV bluprints that can work with J1939 data). Now, if we had, hypothetically speaking a VSS signal for every J1939 data and annmotate it as such, wouldn't we effectively have "published" a form of the non-free digital annex of that standard?

[erikbosch]

MoM:

• Ted presented the issue
• T: Quite common the people reference them by identifiers. We can define a reference syntax
• Scott: Intended usage?
• T: Lookup
• S: Kept separate from the unit definition
• Sebastian: Mostly for humans?
• E: We have in the past discussed VHAL-VSS mapping, a reference syntax could be used to document that, like "VHAL-"
• E. no objection to adding a reference syntax, needs to be well defined/documented list? separators?
• E: If we are to add info to std catalog for a specific "standard", like VHAL or J1939, there must be someone willing to do the work to make it complete and maintain it.
• T: Will update example and check with Daniel
• Scott: Can I append to list with overlay?
• T: Can add/overwrite data
• E: Can not append, I think
• T: Owner/maintainer to be listed.
• E: A syntax like below could be an alternative

reference:
  fms: cccc
  vhal: hhhh

[tguild]

Unsure what the best syntax would be for namespaces in YAML. The only examples I am finding are for Kubernetes (Docker alternative).

https://kubernetes.io/docs/tutorials/cluster-management/namespaces-walkthrough/

I was thinking a namespaces/references file would

fms
type: namespace
uri: https://www.fms-standard.com/Truck/down_load/fms%20document_v_05_vers.24.11.2023.pdf
version: 5
organization: ACEA

j1939
type: namespace
uri: https://www.sae.org/standards/development/ground-vehicle/sae-j1939-standards-collection-on-the-web
comment: no direct link to specification, requires purchase
organization: SAE

then in VSPEC for a given signal:

reference:
fms:1.1.7
j1939:PGN:0xFEC1;SPN:917