COVESA / COVESA/vss-tools

Stable identifier governance for VSS-based modeling projects

Open
#508 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
79
Forks
76
Avg merge
5d 5h
Merged PRs (30d)
7

Description

# Problem
VSS modeling projects face two compounding identification problems:

## 1. FQN-as-identifier is fragile and implicit

In VSPEC projects, the Fully Qualified Name (`FQN`) (e.g., `Vehicle.Cabin.Seat.Row1.DriverSide.Position`) is almost always used as the unique identifier for VSS nodes — in databases, APIs, tooling integrations, and data pipelines. This creates a structural fragility: the identifier is coupled to the tree structure of the model.

When an organization takes the public COVESA VSS as a basis for an internal project and begins overlaying, the ownership question becomes immediately ambiguous.
* Is `Vehicle.Cabin.MyFeature` a COVESA concept or an internal one?
* If the overlay modified the relevant metadata of a node, then its semantics have changed in an incompatible way.
* Who governs its lifecycle?
* If COVESA restructures their tree in a future release, does the internal `FQN` break?
* Renaming or moving a node becomes a painful process with breaking consequences for every downstream consumer that stored the string.

## 2. The existing `export id` approach partially solves it but leaves governance implicit

vss-tools introduced an id exporter that hashes each node together with its associated metadata, producing a deterministic fingerprint per node. If relevant metadata changes, the hash changes and a new ID is produced. The concept of tracking changes was handled via the "formerly known as" (fka) mechanism.

This is a meaningful step forward, but it has limits. The IDs are entirely derived from content — there is no explicit declaration of who minted the ID, under what authority, or for which namespace. When a private project reuses a public specification, the ownership and governance of the ID space remains implicit and ambiguous. A "stable" identifier that changes whenever metadata changes is, in practice, not stable enough for long-term external references.

Suggestion
Borrowing from basic Semantic Web principles: assign identifiers sequentially and bind them to an explicitly declared URI namespace with a preferred prefix for compactness (CURIE form).

A project declares ownership once:
```yaml
namespace:
prefix: vss
uri: "https://www.covesa.global/model/vss#"
```

Nodes are assigned IDs in the order they first appear, starting from 0, per namespace:
```
vss:0 → Vehicle
vss:1 → Vehicle.ADAS
vss:2 → Vehicle.Cabin
```
A private project that overlays COVESA's model declares COVESA as an import and mints only its own new concepts:
```yaml
namespace:
prefix: myns
uri: "https://www.example.org/myModel#"
imports:
vss:
uri: "https://www.covesa.global/model/vss#"
```

```
vss:0 → Vehicle (unchanged, owned by COVESA)
vss:1 → Vehicle.ADAS (unchanged, owned by COVESA)
myns:0 → Vehicle.MyFeature (new, owned by the private project)
```

Ownership is explicit, IDs are stable regardless of tree restructuring, and the namespace URI makes them globally resolvable in any linked data toolchain.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the existing `export id` approach and the “formerly known as” (fka) mechanism in vss-tools. Determine where namespace declarations, imports, and node ID assignment would belong. Done means ownership is explicit, IDs are sequential per namespace, imported concepts remain referenced, and IDs stay stable across tree restructuring.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.