This document, the Gen2 core specification, describes the Gen2 messaging layer. The companion specifications for the Gen2 transport protocols detail the mapping of the messaging layer to selected transports. The ontologies based on the Gen2 core specification are defined in documents for each specific domain (e.g. navigation, media, vehicle data).

Introduction

This document describes the messaging API for Gen2 protocol. This includes the messaging layer and set of rules for structuring data. The separation between payload encoding (transport) and messaging API (core) improves adaptability. Extending and describing multiple transport protocols becomes possible.

The messages are exchanged between a service implementation holding the representation of data and a client using the data. A service is an entity that manages and offers access to data. A client is an entity that works with data managed by a service.

The Gen2 messaging layer uses a RESTful design for all methods exchanged via the interface ().

The Gen2 data structuring rules () are the same through all transport protocols. The basis for structuring data hold by a service is a tree.

Terminology

The acronym 'Gen2' is used to refer to this document, the second generation specification. The acronym 'VSS' is used to refer to the 'Vehicle Signal Specification' which is defined by the GENIVI Alliance. The term 'WebSocket' when used in this document, is as defined in the W3C WebSocket API and the WebSocket Protocol.

Gen2 Multi Domain Vehicle Taxonomy

The Taxonomy wich is served through this interface is the Gen2 Multi Domain Taxonomy. It is an aggregation of different Domain Taxonomies. The single entry point and master of the Gen2 Multi Domain Taxonomy SHALL be the Vehicle Domain Taxonomy.

Domain Taxonomies

The basic structure of the taxonomy is a tree. Its goal is to formalize the description of a specific domain. It consists of the Rule Set, Data Definition and Tools.

Rule Set

The Rule Set defines how to syntactically describe the taxonomy. The data structure is a tree, where a leaf is understood as a nodes without children. All other nodes are called branches. Branch Entries represent the logical structure of the domain, where Data Entries as leafs define the actual data.

Schema Files

A domain specification MUST be written as a flat YAML list, where each signal and branch is a self-contained YAML list element.

The YAML list is a single file, called a vspec file. A vspec can, in addition to a YAML list, also contain include directives. An include directive refers to another vspec file that is to replace the directive, much like #include in C/C++.

Please note that, from a YAML perspective, the include directive is just another comment.

Branch Entry

to be described more (see here)

Data Entry

to be described more (see here)

Types

sensor

A leaf that describes non-static read-only signal.

attribute

A leaf that describes static read-only value.

stream

A leaf that references a data stream, e.g. a video stream.

actuator

A leaf the same as sensor which additionaly can be changed.

element

to be described

Data Types

Number

Number is used to represent numbers. This includes all signed and unsigned integer values and floats. To allow for memory allocation restrictions MUST be given. Restrictions MUST be expressed by using min, max and precision. Min MUST describe the lowest possible value. Min MUST be defined as base to the power of min (i.e. b^min). Max MUST describe the highest possible value. Min MUST be defined as base to the power of max with an optional -1 (i.e. b^max - 1). Precision MUST describes the smallest changeable amount in the value. Precision MUST be defined as base to the power of precision (i.e. b^n). A schema MAY define the restrictions by using predefined restrictions.

name description min max resolution
UInt8 unsigned 8-bit integer 0 255
Int8 signed 8-bit integer -128 127
UInt16 unsigned 16-bit integer 0 65535
Int16 signed 16-bit integer -32768 32767
UInt32 unsigned 32-bit integer 0 4294967295
Int32 signed 32-bit integer -2147483648 2147483647
UInt64 unsigned 64-bit integer 0 2^64-1
Int64 signed 64-bit integer 2^63 2^63-1
Float floating point number -3.4e -38 3.4e 38
Double double precision floating point number -1.7e -300 1.7e 300

Boolean

Simple true or false

String

String is used to represent sequence of characters. To allow for memory allocation restrictions MUST be given. Restrictions MUST include a maximum string length. Restrictions MAY include a character set. If no character set is given unicode MUST be assumed. Restrictions MAY include a regular expression. which regex style? A schema MAY define the restrictions by using predefined restrictions. Protocol specific implementations MAY use optimized versions to transfer values with predefined restrictions.

name description max example RegEx
date-time date-time (based on RFC3339 5.6) detailed fraction 29 2005-11-12T12:01:42.123+01:00 ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?((Z|(\+|\-)\d{2}:\d{2}))$
time time (based on RFC3339 5.6) detailed fraction 18 12:01:42.123+01:00 ^\d{2}:\d{2}:\d{2}(\.\d{3})?((Z|(\+|\-)\d{2}:\d{2}))$
date date (RFC3339 5.6) 10 2005-11-12 ^\d{4}-\d{2}-\d{2}$

ByteArray

ByteArray, also known as a blob, is an array of bytes of not nearer specified data. To allow for memory allocation restrictions MUST be given. Restrictions MUST include a maximum number of bytes.

Data Definition

The Data Definition is the representation of a specific domain under using the Rule Set described before.

Vehicle Domain Taxonomy

It is derived from GENIVI's Vehicle Signal Specification (VSS). It resembles the physical structure of the vehicle, as shown in the This example. Major vehicle structures (e.g. body, engine) are near the top of the tree and the logical assemblies and components that comprise them, are defined as their child nodes. Each of the child nodes in the tree is further decomposed into its logical constituents, and the process is repeated until leafs are reached.
Diagram showing an example tree.

Tools

to be described more

Addressing

Addressing of elements is done using URIs as defined in [[RFC3986]].

scheme:authority/path

The scheme describes the protocol to use to reach the addressed element. The authority describes where to reach the service holding and managing the data representation. Scheme and authority are defined within the protocol adaptation.

Path describes the location of a specific data representation within a service. It is the path through the tree, the data representation, implemented by the service.

Service discovery

The client MAY request that the server returns the VSS tree content. The client is able to request metadata from any point in the signal tree, such that only the metadata for the nodes within the given branch of the tree is returned. For example, only metadata for the chassis branch of the VSS tree is returned when the chassis path is specified. If the path is set to the VSS root, the response contains the metadata for the entire tree. If the server is able to satisfy the request it SHALL return a Response message. If an error occurs the server SHALL return an ErrorResponse message. The key data components of these messagess are defined below:

Filtering

This section describes how to build the queries to filter for specific parts of the data representation.

A query is a description to taylor and filter the data resulting of a read.

The query can be given with the request from a client to a service additionally to the path to get a content response. The query describes certain rules that filter the content response.

Example

All open doors shall be given. The tree looks as follows:

  • /vehicle/cabin
    • /Row1
      • /Left
        • /Door
          • isLocked: true
          • open: false
      • /Right
        • /Door
          • isLocked: false
          • open: true
    • /Row2
      • /Left
        • /Door
          • isLocked: false
          • open: false
      • /Right
        • /Door
          • isLocked: true
          • open: true

The path that shall be inspected is "/vehicle/cabin".
The rule is that "/vehicle/cabin/*/*/Door/isLocked" shall be "true".

The list in the content response would look like this:

  • /vehicle/cabin/Row1/Left/Door
    • isLocked: true
    • open: false
  • /vehicle/cabin/Row2/Right/Door
    • isLocked: true
    • open: true

Rules

A rule is an expression that describes a characteristic of nodes that shall be returned by a query. Rules are applied to a leaf and describe a desired attribute of a node. All rules MUST return either FALSE or TRUE.

These are the rules that are known to check to be used in a query to filter content responses.

nameinput typeDescriptionExample
true boolean matches if the data value is true true(isLocked)
false boolean matches if the data value is false false(isLocked)
contains string matches if a given string is contained in another one contains(name, "blue")
equal (string|boolean|number) matches if a value is equal to a given value equal(name, "Red Door")
greaterThan number matches if a given number is greater than the value greaterThan(windowPosition, 0.2)
smallerThan number matches if a given number is smaller than the value smallerThan(windowPosition, 0.2)
greaterThanEqual number matches if a given number is greater than the value or equal to the value greaterThan(windowPosition, 0.2)
smallerThanEqual number matches if a given number is smaller than the value or equal to the value smallerThan(windowPosition, 0.2)

It MUST be possible to combine several rules to one greater rule. This is possible with the following operators.

not rule negates the return of a rule not(true(isLocked))
and rule,rule returns true if both of the rules evaluates true and(ruleA,ruleB)
or rule,rule returns true if one of the rules evaluates true or(ruleA,ruleB)

Security

The security section has to be described. Helpful discussion might be:
Authentication: http://www.w3.org/2018/04/19-auto-minutes.html#item03
Volvo assesment: https://lists.w3.org/Archives/Public/public-automotive/2018Aug/0002.html, https://www.w3.org/2018/09/25-auto-minutes.html#item01

Interface

This chapter describes the different methods and its arguments that govern the communication between a service and a client.

Methods

A timeout for the response of all methods with responses MUST be defined. This timeout is transport protocol specific to reflect the normal behaviour of the transport protocol.

All methods should list the possible error types returned.

read

Purpose: obtain a representation of the value addressed by the given path

The service MUST expose a read method. The client MAY use the read method of the service to retrieve values managed by the service. If the service is able to satisfy the request it MUST return a content response. If the service is unable to fulfil the request, then the service MUST return an error response. The client MAY have to authenticate via the authenticate method before being able to access the values.

arguments:

  • path fully qualified path to a base node
  • filter selection criterias for specific values under the given path

responses:

  • content response fulfilling the request
  • error response describing what went wrong

update

Purpose: providing altered values to the service for a specified path

The service MAY expose an update method. The client MAY use the update method of the service to request a change to values managed by the service. If the service is able to satisfy the request it MUST return a change response. If an error occurs the service MUST return an error response.

arguments:

  • path fully qualified path to a base node
  • filter selection criterias for specific values under the given path
  • change new value that shall be applied

responses:

  • change response describing what went well
  • error response describing what went wrong

create

Purpose: providing new values to the service under a specified path

The service MAY expose a create method. The client MAY use the create method of the service to request new values to be managed by the service. If the service is able to satisfy the request it MUST return a change response. If an error occurs the service MUST return an error response.

arguments:

  • path fully qualified path to a base node
  • change new value that shall be added

responses:

  • change response describing what went well
  • error response describing what went wrong

delete

Purpose: removing all selected values under a specified path

The service MAY expose a delete method. The client MAY use the delete method of the service to request the deletion of existing values managed by the service. If the service is able to satisfy the request it MUST return a change response. If an error occurs the service MUST return an error response.

arguments:

  • path fully qualified path to a base node
  • filter selection criterias for specific values under the given path

responses:

  • change response describing what went well
  • error response describing what went wrong

subscribe

Purpose: monitor changes made to values under a specified path

The service MAY expose a subscribe method. The client MAY use the subscribe method of the service to request being informed of changes made to values managed by the service. The service MUST issue a notification if the equivalent read content response would change. If the service is able to satisfy the request it MUST return a subscription and contract response. If an error occurs the service MUST return an error response.

arguments:

  • path fully qualified path to a base node
  • filter selection criterias for specific values under the given path
  • contract describing the expectations for the client receiving notifications

responses:

  • subscription response describing the status of the subscription
  • contract describing the rules for the service sending notifications to the client
  • error response describing what went wrong

notify

Purpose: informs of changes made to values under a subscription

The client MUST expose a notify method if it uses the subscribe method of a service. The service MUST use the notify method of the client to inform of changes made to values managed by the service under the given subscription by sending a content response. The service MUST ignore any response from the client.

arguments:

responses: none

unsubscribe

Purpose: stop monitoring the changes made to values under a subscription

The service MUST expose a unsubscribe method if an subscribe method is exposed. The client MAY use the unsubscribe method of the service to cancel being informed of changes made to values managed by the service under the given subscription. The service MUST stop issuing notifications. If the service is able to satisfy the request it MUST return a subscription response. If an error occurs the service MUST return an error response.

arguments:

responses:

  • subscription response describing the status of the subscription
  • error response describing what went wrong

Arguments and Responses

content

  • Value: One or more values associated with the addressed VSS leaves.
  • Timestamp: A timestamp associated with the request.

filter

criterias to filter according to a query

path

see addressing

change

  • changed applied immediately or later
  • list changed paths

subscription

status of the subscription

contract

describing the rules for subscriptions/notifications

error

An error response MUST include the formal error type. An error response MAY include a textual form of the error type. An error response MUST include an error value if obligatory for the error type. An error response MUST include a timestamp. An error response MUST be actionable.

fieldobligationdescriptionformatexample
error type mandatory short handle describing the error. protocol specifc AuthorizationFailed
error description optional Information describing the error reason. ^[\w ]{5,255}$ Authorization failed for the method. Please set a valid AuthToken and AuthType.
error value conditional Send if set as mandatory for the error type. Describing more details to understand the error type. string, error type specific AuthToken valid; Access Level not sufficient.
timestamp mandatory The time when the error occured. date-time compliant 2005-11-12T12:01:42.123+01:00
Do we really need an error value as all method calls are directly mapped to error response.
How do we want to handle timestamps? Is this something that is signaled through the meta-data for the call of the method? Is this something every method must have?

Error Types

These error types MUST be implemented by a service. A transport protocol MAY define additional error types. A transport protocol MUST not alter these error types.

error typeTextual descriptionvaluesSolution/Action
InvalidToken The AuthToken is not recognized as valid. none Check if AuthType is set correctly. Get a new AuthToken.
AccessLevelNotSufficient The AuthToken is recognized but does not allow the execution of the requested method. none Get a token with a different access level.
InvalidPath The given path is not valid. none Check the path given in the arguments.
MissingArgument An mandatory argument is missing from the method execution. Missing Argument Add missing argument.
InvalidFilter Filter could not be parsed. Error Position Fix filter.
ValueNotPermited A value set by the client is not permited. value Set the value to a value permited by the service implementation.
ContractInvalid The contract submitted is not valid. Invalid contract statement Recall method with a valid contract.
SubscriptionUnknown The subscription is not known by the service. none Check subscription.
Would examples for the error types be helpful?
Where best to describe error types?

Meta-Data

The title for this chapter is not good.

For the communication between service and client several key/value pairs can be given to describe the environment in what the methods () are called. The string describing the key MUST be the same structure as name.

authorization

Purpose: authorization makes it possible for a client to authorize itself towards a service.

The authorization key/value pairs consists out of a AuthType and a AuthToken key/value pair. The client MAY use the authorization key/value pairs to transfer an authorization token to the service. The client MUST use either both key/value pairs or none of the two. The service MAY use the token transfered by the AuthToken key/value pair to authenticate the client. The client MUST set the type of the token with the AuthType key/value pair if AuthToken is set. This concept MAY be used for access control. A rejected authorization token MUST result in an error response. If the execution of a method on a service needs authorization the service MUST use the authorization key/value pair.

key AuthToken
value ^\w{1,1024}$
How long should the maximum length of a token be to be easily implemented by most protocols.
key AuthType
value name compliant

variant selection

Purpose: A client can express which schema variants it can support when executing a method. A service can express which schema variant it uses when communicating with the client.

The client MAY set multiple key/value pairs to describe all variants it supports. The client MAY not set any key/value pair. The service MUST set exactly one schema key/value pair to describe the used variant. The client MAY use the [[SemVer]] style to describe degrees of freedom in the version of the schema.

key Schema
value schema compliant
examplew3c.vehicle.v1.5.3