The Vehicle Signal Specification domain specification consist of vspec files.
vspec files are YAML files following the rule set defined for VSS.
They also support the use of include directives to refer to other vspec files, much like #include
in C/C++. .
Please note that, from a YAML perspective, the include directive is just another comment.
The file VehicleSignalSpecification.vspec serves as root and includes other vspec files from the VSS repository.
The raw specification files can, with help of tools in the vss-tools repository, be converted to other formats that are more user friendly to read. Converted representations are also included as release artifacts for each VSS release.
VSS is in itself case sensitive. This means that keywords, signal names, types and values normally shall be given with the case specified. It is however recommended not to take advantage of this and reuse the same name with different case, as some implementations may treat VSS identifiers as case insensitive.
Tree nodes are addressed, left-to-right, from the root of the tree
toward the node itself. Each element in the name is delimited with
a period ("."). The element hops from the root to the leaf is called path
.
For example, the dimming status of the rearview mirror in the cabin is addressed:
Vehicle.Cabin.RearviewMirror.Dimmed
If there are an array of elements, such as door rows 1-3, they will be addressed with an index branch:
Vehicle.Cabin.Door.Row1.Left.IsLocked
Vehicle.Cabin.Door.Row1.Left.Window.Position
Vehicle.Cabin.Door.Row2.Left.IsLocked
Vehicle.Cabin.Door.Row2.Left.Window.Position
Vehicle.Cabin.Door.Row3.Left.IsLocked
Vehicle.Cabin.Door.Row3.Left.Window.Position
In a similar fashion, seats are located by row and their left-to-right position.
Vehicle.Cabin.Seat.Row1.Pos1.IsBelted # Left front seat
Vehicle.Cabin.Seat.Row1.Pos2.IsBelted # Right front seat
Vehicle.Cabin.Seat.Row2.Pos1.IsBelted # Left rear seat
Vehicle.Cabin.Seat.Row2.Pos2.IsBelted # Middle rear seat
Vehicle.Cabin.Seat.Row2.Pos3.IsBelted # Right rear seat
The exact use of PosX
elements and how they correlate to actual
positions in the car, is dependent on the actual vehicle using the
spec.
If a new leaf node is defined, all parent branches included in its name must be included as well, as shown below:
[Signal] Vehicle.Cabin.Door.Row1.Left.IsLocked
[Branch] Vehicle.Cabin.Door.Row1.Left
[Branch] Vehicle.Cabin.Door.Row1
[Branch] Vehicle.Cabin.Door
[Branch] Vehicle.Cabin
[Branch] Vehicle
The branches do not have to be defined in any specific order as long as each branch component is defined somewhere in the vspec file (or an included vspec file).
since version 2.1
During the process of model development, nodes might be moved or deleted. Giving developers a chance to adopt to the changes, the original nodes are marked as deprecated with the following rules.
V
(e.g. V2.1
) followed by the reason for deprecation.moved to
followed by the new node name in dot notation as deprecation reason. This keyword shall be used only
if the meta-data of the moved node hasn’t changed.removed
and optionally the reason for the removal as deprecation reason.Vehicle.Navigation.CurrentLocation:
type: branch
description: The current latitude and longitude of the vehicle.
deprecation: V2.1 moved to Vehicle.CurrentLocation
It is recommended for servers, which are implementing protocols for the vehicle signal specification, to serve old and new nodes during the deprecation period described above.
The VSS specification must adhere to YAML syntax. To keep the standardized VSS specification in this repository consistent the following style guide is provided.
The recommended naming convention for node elements is to use camel case notation starting with a capital letter. It is recommended to use only
A-Z
, a-z
and 0-9
in node names. For boolean signals it is recommended to start the name with Is
.
Examples:
SomeBranch.AnotherBranch.MySignalName
Vehicle.Cabin.Door.Row1.Left.IsLocked
Naming convention for string literals can be found in the chapterfor specifying allowed values.
It is recommended that line length for files in this repository ( e.g. *.vspec
and *.md
files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs present in files over multiple lines.